22. Files and folders

What ucm init creates, what ucm writes as it works, and what to keep in version control.

myproject/
  package.json            "#codebase" and "#ucm/server" imports; your npm dependencies
  tsconfig.json           compiler options (see compiler options)
  scratch.ts              where you write; any top-level .ts file is a scratch file
  .ucm/
    codebase.sqlite       the codebase: definitions, names, history, branches, patches, todo
    codebase/             the #codebase modules your scratch files import (generated)
    cache/                every definition as a runnable module, by hash (generated)
    data/                 app data: tables, sessions, jobs (created when an app first runs)
    apps/                 production builds, by hash (ucm build / ucm start)
    web/, build/          working files for ucm dev and ucm build (generated)
    examples/             doc examples, as runnable modules (generated)
    secret, tls/          the server's session secret and TLS certificate, once there are any
    .gitignore            ignores everything above except codebase.sqlite

22.1 What to keep

• .ucm/codebase.sqlite is the codebase. Everything else in .ucm/ except data/ is generated from it and rebuilt when missing. To share a codebase, use sync (ucm push / ucm pull); copying the file works too.
• .ucm/data/ is your app's data. Back it up like any database; don't commit it (it holds sessions), and don't commit secret or tls/ either.
• package.json, tsconfig.json are worth committing: they're your project's packages and compiler settings.
• Scratch files are optional to keep: once code is added, it lives in the codebase.

ucm init writes .ucm/.gitignore, which leaves only codebase.sqlite to commit: generated directories, app data and secrets are all ignored.

22.2 The two imports

ucm init adds these to package.json's imports:

• #codebase, #codebase/<namespace>: your saved definitions, as modules. They're regenerated whenever names change, so your editor's autocomplete and type checking always match the codebase.
• #ucm/server: the server API.

22.3 Generated modules

.ucm/cache/<hash>.ts holds each definition as a module, with current names spliced in and imports by hash. Node runs these directly; there's no build step. You can read them, but there's no need to: ucm view, and in VS Code Go to Definition, show the source.

built from 5890e54f