aicoded.dev

Start a new app

Create an app with aicoded init, declare in its permission list what it reaches, open its building blocks once in a deps package that every page shares, and run it under aicoded dev. The code is that of the people example, a staff directory, and of contacts, an app with no pages.

Steps

  1. In the folder that holds your apps, run aicoded init people. It makes the folder people/ with go.mod, the permission list aicoded.yaml, main.go, one page, pages/index.html, AGENTS.md, the rules for AI assistants that build the app, and a .gitignore that keeps the draft of schema changes, .aicoded/migration.sql, out of git. It then runs aicoded generate and go mod tidy. The name is 2 to 63 lowercase letters, digits and dashes, starting with a letter and ending with a letter or digit (E-CLI-002).

  2. Write in aicoded.yaml what the app reaches. The finished people app has its own SQL database, a file store named photos, mail to its company's domain, and one setting, the team's address:

    app: people
    audience:
      internal: [everyone]
    data:
      - source: sqldb
        classes: [internal]
      - source: filestore:photos
        classes: [internal]
    email:
      from: people@acme.example
      to_domains: [acme.example]
    settings: [team_address]
    # access is written by aicoded generate from <ssr:access>; do not edit it
    access:
      "/contact":
        require: ["*"]
      "/home":
        require: ["*"]
      "/users/add":
        require: ["staff", "hr"]
      "/users/{login}/contacts":
        require: ["staff"]
        guard: true
      "/users/{login}/info":
        require: ["staff"]
        shared: true
    # services is written by aicoded generate from rpc/ and the clients in services/; do not edit it
    services:
      calls:
        "contacts": ["Contacts"]
    

    You write app, data, email, settings and secrets, so copy only those sections. aicoded generate writes the access section from the pages and the services section from the calls between apps; never edit those two. When the person says who owns and uses the app, write owner and audience too, as the permission list describes.

  3. Make deps/deps.go, package deps, with a type Deps for what every page shares and a Start that opens the building blocks before the app serves:

    // Deps is made by New and filled by Start before the app serves.
    type Deps struct {
    	DB     *sql.DB
    	Photos *filestore.Store
    	// TeamAddress is the setting team_address, where the app mails the team.
    	TeamAddress string
    	// HomePages has one subscription per open home page, and a signal whenever one opens or
    	// closes.
    	HomePages *reactive.Broadcast[struct{}]
    	// UsersAdded signals that a user was added.
    	UsersAdded *reactive.Broadcast[struct{}]
    	// Seen records when each viewer last opened a page.
    	Seen *LastSeen
    }
    
    // New returns Deps with its hubs.
    func New() *Deps {
    	return &Deps{
    		HomePages:  reactive.NewBroadcast[struct{}](),
    		UsersAdded: reactive.NewBroadcast[struct{}](),
    		Seen:       NewLastSeen(),
    	}
    }
    
    // Start opens the database and the photo store, fills the users table when it is empty and reads
    // the team's address.
    func (d *Deps) Start(ctx context.Context) error {
    	db, err := sqldb.Open(ctx)
    	if err != nil {
    		return err
    	}
    	if err := fill(ctx, db); err != nil {
    		return err
    	}
    	photos, err := filestore.Open(ctx, "photos")
    	if err != nil {
    		return err
    	}
    	team, err := config.String(ctx, "team_address")
    	if err != nil {
    		return err
    	}
    	d.DB, d.Photos, d.TeamAddress = db, photos, team
    	return nil
    }
    

    fill comes from List rows from the database, and LastSeen and NewLastSeen from Add a live value: leave them and the live hubs, HomePages, UsersAdded and Seen, out until you need them.

    Start creates no table: the app's tables come from its draft of schema changes, .aicoded/migration.sql, which aicoded dev applies before the app starts and aicoded publish sends with the commit. App code that changes the schema is refused (E-LINT-013). See Schema changes.

    There is no DSN and no password. sqldb.Open, filestore.Open and config.String reach, through the runner, only what the permission list declares, and refuse anything else (E-MAN-010, E-MAN-011, E-MAN-001).

  4. In main.go, pass Start to app.Main as OnStart, and the Deps to the pages:

    // People is a staff directory: staff look up their colleagues, and hr adds new ones.
    package main
    
    import (
    	"aicoded.dev/framework/app"
    
    	"people/deps"
    	"people/pages"
    )
    
    func main() {
    	d := deps.New()
    	app.Main(app.Options{Handler: pages.NewHandler(d), OnStart: d.Start})
    }
    
  5. Once deps declares Deps, the pages.NewHandler that aicoded generate writes takes a *deps.Deps and passes it to the NewDP of every page. The page that aicoded init made still has NewDP(): delete pages/dataprovider.go, which holds no code of yours yet, and run aicoded generate, which writes it again with the *deps.Deps.

  6. Give aicoded dev the local values in dev.yaml, in your user configuration directory (~/.config/aicoded/dev.yaml on Linux, ~/Library/Application Support/aicoded/dev.yaml on macOS), with mode 600. The workspace is the absolute path of the folder you run aicoded dev in. An app with sqldb needs the admin DSN of a MySQL 8 server on this machine, and every setting needs a test value:

    workspaces:
      /absolute/path/to/apps:
        mysql: root:<password>@unix(/run/mysqld/mysqld.sock)/
        personas:
          - {name: alice, roles: [staff]}
          - {name: bob, roles: [staff, hr]}
          - {name: carol}
        apps:
          people:
            settings: {team_address: team@acme.example}
    
  7. Run aicoded dev in that folder and open http://people.localhost:8080/ in Chrome. Switch personas at http://people.localhost:8080/_aicoded/persona.

An app with no pages

contacts serves a function to people and has no pages. Its main passes only the generated server of its rpc/ package, and its Start is a plain function:

// Contacts serves the phone numbers and email addresses of people to the people app.
package main

import (
	"aicoded.dev/framework/app"

	"contacts/deps"
	"contacts/rpc"
)

func main() {
	app.Main(app.Options{RPC: rpc.Server(), OnStart: deps.Start})
}
// Start opens the app's database and fills the contacts table when it is empty.
func Start(ctx context.Context) error {
	conn, err := sqldb.Open(ctx)
	if err != nil {
		return err
	}
	if err := fill(ctx, conn); err != nil {
		return err
	}
	db = conn
	return nil
}

Its table, contacts, comes from its draft, .aicoded/migration.sql, as people's does. Its permission list declares only its database. aicoded generate adds access: {} and the function it serves:

app: contacts
audience:
  internal: [everyone]
data:
  - source: sqldb
    classes: [internal]
# access is written by aicoded generate from <ssr:access>; do not edit it
access: {}
# services is written by aicoded generate from rpc/ and the clients in services/; do not edit it
services:
  serves:
    "Contacts":
      callers: ["people"]
      require: ["staff"]

Check it

See also

Markdown · Source on GitHub · framework f46741f