@happyvertical/smrt-app-shell 0.60.18 → 0.61.0

package/agents/draft-ui.md

@@ -0,0 +1,74 @@
+# Draft UI validation
+
+The content header owns draft controls on home, model, history and review pages; welcome and settings have none. Chat is hidden during onboarding. The publish preview groups Added, Removed, Changed and Archived items in counted cards before its ordered changes and full method code. The saved owner view selects the
+layout description; loaders and mutations carry that description's explicit
+target. Changing copies remounts forms and returns home. Approvals always name
+live. No report route is present. Shell copy uses the existing plain-text
+pattern (the package has no message catalog).
+
+| Behavior | Trigger and positive case | Failure case | Context / executor | Runtime / edge | Level / command |
+|---|---|---|---|---|---|
+| Content controls | Owner starts draft; count, switch, actions, chat badge | Unpublishable draft disables switching/review; discard remains | Owner browser, shell routes | Svelte 5 / draft events | DOM / package test |
+| Explicit copy | Switch persists view; description drives reads and writes | Failed switch keeps rendered copy; other-copy record events ignored | Owner, server event.fetch and browser fetch | Node 26 + jsdom / REST and MCP targets | Node + DOM / package test |
+| Draft records | Draft delete 200 navigates away | Live delete 202 waits for approval | Owner, existing server gate | SQLite through server (unchanged) | DOM / package test |
+| Navigation | Draft-only model has new badge | Live lists only live models | Owner layout | jsdom / describe | DOM / package test |
+| Review | Full preview, all code and archive counts | Chain change before request or approval offers review again | Owner gesture, pinned Approval | jsdom / preview + publish + decide | DOM / package test |
+| History | Publish versions grouped, undo-to uses first parent | Purged/current boundaries disable undo; 202 links to approvals | Owner, existing undo transaction | Node 26 + jsdom / history | Node + DOM / package test |
+| Lifecycle | Started/published/discarded/unpublishable refresh dependencies | Unknown events ignored; reconnect refreshes all | Owner SSE subscription | jsdom / EventSource | DOM + Node / package test |
+| Live data survives | Define, fork, edit, write live, publish, undo, discard | Draft test rows excluded on publish | Owner HTTP session, real engine | Node 26 + SQLite / production server | Manual / README Run it |
+
+Database/auth contracts and transactions are unchanged; their negative cases
+remain covered by the existing server suites. This is a new UI, so a bug-fix
+base comparison is not applicable. No containers or external services are needed.
+
+Manual execution (Node 26.12.1, production adapter-node build, port 4821):
+`smrt app setup` with a fresh real path under `/private/tmp`, then `node build`.
+Created the owner through the setup form. Authenticated curl calls defined Chore,
+seeded a live row, converted points and removed obsolete in the draft, added Note
+and a code method, and added separate live/draft records after the fork. The
+review UI showed full code and archive counts. Changing the chain after review
+refused Publish and offered Review again. Publishing through its Approval kept
+the new live row (points converted to 8), excluded the draft-only row, and tagged
+all five versions. History's Undo this publish raised an Approval; approving
+restored the text field and archived obsolete value and retained the live row.
+Started another draft and confirmed Discard. At 390×844, the content controls
+wrapped without horizontal overflow and retained the warning; the new marker
+used the warning token. Stopped the server by PID and removed session cookies
+and temporary runtime data. No browser page errors were observed.
+
+## Desktop QA regressions
+
+All rows below use the signed-in owner, Node 26 and in-process SQLite where
+persistence is involved; no transaction or schema behavior changes. DOM cases
+run with `vitest run -c vitest.dom.config.ts`, server cases with `vitest run`.
+The package `test` command runs both. Each regression is checked against its
+pre-fix implementation as well as the fixed code.
+
+| Behavior | Reachable trigger / positive | Negative / failure | Executor / edge | Level |
+|---|---|---|---|---|
+| Assistant readiness | Connect Claude Code or ChatGPT, save key; open composer updates | Sign out disables composer; failed requests preserve known state | Browser connection controls and status route; no credentials in events | DOM |
+| Onboarding chat | Welcome or unfinished onboarding hides panel | Finished/skipped onboarding restores saved chat choice; plugin stays hidden | Layout server data and browser layout | DOM |
+| Draft bar routes | Home, model list/record, history and review show controls | Welcome and all settings pages hide controls | Browser pathname | DOM |
+| Per-turn mode | Start draft after existing conversation, change viewed copy, resume CLI | No draft after discard/publish replaces stale draft context | Stub model and Claude Code/Codex subprocesses; same tool scopes | Node |
+| Tool summaries | Builder summary and describe/list phrase | No raw JSON, SQL or snapshot paths; unknown tools get generic phrase | API and CLI events, stored thread replay, HTTP responses | Node + DOM |
+| Attribution | Owner id resolves to profile name; recorded assistant and engine remain | Unknown identity uses neutral label; spacing survives DOM rendering | Session profile, approval cards and history | DOM |
+| Phone navigation | 375px starts on content, drawer can open on demand | Desktop expanded preference never opens phone drawer; title can ellipsize | Shared shell responsive state | DOM + browser |
+| Publish review | Added/Removed/Changed/Archived groups, counts, ordered changes, full code | Empty groups show zero; conversions and archives remain visible | Existing preview payload; UI primitives and tokens | DOM |
+
+QA rerun (2026-11-10, Node 26.12.1, production `node build`, fresh data
+outside the checkout, port 4822, desktop owner-link auto-sign-in): native Chrome
+showed welcome without chat or draft controls. Selecting Claude Code and finishing
+Fresh opened an enabled composer saying “Using Claude Code” without a reload.
+Settings had no draft controls. Seeded Product and OldModel, started a draft from
+the UI, then added Supplier, a notes field and a method, removed a field/model,
+and converted money to integer through the authenticated routes. Review showed
+Added 3 / Removed 2 / Changed 1 / Archived 3, then six ordered changes and full
+method code. Its approval said “Asked just now by” the owner's profile name;
+after approval, History showed that name and retained “engine” on version 0.
+At Chrome's 375×812 responsive viewport, a fresh page load showed content,
+the full app name and bottom tabs with the drawer closed. Menu opened and closed
+it; returning to desktop restored the expanded sidebar. The console was empty.
+Real paid model turns, ChatGPT OAuth and real key saves were not exercised;
+connection transitions and resumed-engine inputs were verified with DOM tests,
+the stub model and both stub CLIs. Each numbered fix has failing pre-fix
+regression evidence and passing fixed-code evidence. No containers were used.

package/agents/engine.md

@@ -75,6 +75,85 @@ Covered by core's `runtime-model.test.ts` and engine `profile-subclass.test.ts`.
   params, code), so what the owner approves is what is shown; a template with
   more than 200,000 characters of method code is refused as unreviewable.
 
+## Drafts (draft then publish)
+
+A draft is a second `AppHost` over a COPY of the live data in its own
+directory; publishing replays its changes onto the live data. The engine side
+is documented here; the shell's tables, approvals and UI sit on top.
+
+- **Frozen host.** `HostOptions.frozen` / `host.setFrozen(bool)`: `plan` and
+  `execute` of every command in `STRUCTURAL_COMMANDS` (all but
+  `exportTemplate`, incl. `undo`, `cleanUp`, `importTemplate`) throw
+  `EngineError('refused')`; an unknown command type counts as structural.
+  `STRUCTURAL_COMMANDS` is a total `Record<CommandType, boolean>`, so a new
+  command must pick a side. Records, reports, the app's tools and REST keep
+  working. The shell freezes the live host while a draft is open.
+- **`autoApprove`** (risky commands, `_delete` tools, REST `DELETE`) is read
+  once at construction into a `#private` field: no setter. `AppHost.open`
+  refuses it unless the directory holds the engine's draft marker
+  (`.smrt-draft.json`, written only by `forkDraft`) naming a different live
+  directory. A live directory never has a marker.
+- **`live.forkDraft(draftDir, { store })`** (queue, calls drained): worker op
+  `copyTo(path)` is `VACUUM INTO` (one consistent state, no -wal/-shm needed).
+  The call creates `draftDir` (must not exist, must not be/contain/lie inside
+  live), copies `app.db`, writes the marker, seeds the EMPTY draft store with
+  a copy of live's current record (the draft's BASE, same version number; not
+  a draft version) and returns a draft host (`host.draft` is the marker,
+  `autoApprove` on). Failure removes only the directory it just created. A
+  draft can neither fork nor `undo` below its base. Draft versions are
+  numbered `maxVersion + 1` in the draft store. `draft.discard()` closes the
+  host and deletes its directory, only if it holds the marker, is not a symlink
+  and does not contain the live directory (`discardDraftDirectory(dir)` does the
+  same for an orphan). A restart reopens a draft with
+  `AppHost.open(dir, { store, autoApprove: true })`.
+- **Publish** (`publish.ts` helpers, `host.ts` orchestration). `live.previewPublish(draft)`
+  returns a `PublishPreview`: per-version steps and SQL, definition diff, archive
+  counts and EVERY method in full, from a rehearsal on a fresh copy of the CURRENT
+  live data (live only waits while the copy is taken); `digest` pins the draft's
+  chain. `live.publishDraft(draft, { author, approved: true, expect: digest, draftName? })`
+  refuses without `approved`, without the digest, if the chain or the app it
+  started from changed, or if a `.prepublish` file is lying around. Inside the
+  queue, calls drained: copy live, replay each draft version in order (one short
+  worker per version, its stored definition and steps, the number it will get in
+  live; so add-then-rename works), write the result as ONE file (`VACUUM INTO`),
+  copy the old data to `snapshots/<ts>-0-migrate-prepublish.db`, write
+  `publish-journal.json`, retire the live worker, rename `app.db` (+ `-wal`,
+  `-shm`, `-journal`; main file last) to `<name>.prepublish`, rename the new file
+  in, start the worker, write the versions to the store, then remove journal,
+  asides and rehearsal. The versions are N ordinary live versions numbered after
+  the store's HIGHEST (live may sit on an undone branch), parent-chained,
+  summaries tagged `[draft: name] ...`; archives are keyed by those numbers so
+  `undo` works. Draft records are not carried. Any failure before the store is
+  written renames the asides back (live's `app.db` is byte-for-byte what it
+  was, same version) and restarts the old app; `onStage` lets tests fail each
+  stage. Use a store with the optional atomic `commit(records, current)`; without
+  it a failure mid-append leaves unreachable orphan versions. The queue is held
+  until then, so nothing writes to the new file before the commit.
+- **Boot reconcile** (`reconcilePublish`, every `AppHost.open`, before the app
+  starts; result in `host.recovery`): a journal whose `finalVersion` is the
+  store's current only needs its leftovers removed; any other journal is ROLLED
+  BACK (asides restored, the new file removed), not forward: nothing could have
+  written to the new file, and the draft stays open to publish again. An
+  unreadable journal refuses to start rather than guess. Stray
+  `publish-rehearsal-*` directories are removed.
+- **`undoTo`** is a command (`{ type: 'undoTo', version, from? }`, structural, so
+  frozen hosts refuse it): the same step as `undo` repeated newest first for
+  every version after `version` on the current path, one plan, one decision.
+  It is `risky` (approval) when any of them has a `convertColumn` step, with the
+  summed `countOverwrites` preview; a purged version in the span refuses it
+  before anything changes. Each step is its own consistent state, so a failure
+  part-way leaves the app at the version reached and the error says
+  "undid k of n". `from` pins the current version as `undo`'s pin does.
+- **Undo over a re-added name.** Undoing an add or a define keeps its column or
+  table (data is never dropped by an undo). So when a removal is undone after
+  the same field or model was added again, the archived values go back into the
+  column that is there, and an EMPTY table of the model's name is dropped so the
+  archived table (with its rows) can return; a table holding rows is never
+  dropped and the undo stops with the database's own message.
+- **Queued calls.** `onApp` (records, tools, REST) waits until the change queue
+  is idle and stable, then runs in the same synchronous step; it counts
+  in-flight calls so a change can wait for them (needed for consistent copies).
+
 ## Lessons
 
 - A worker must not be terminated while `@happyvertical/sql`'s startup HMAC key
@@ -83,3 +162,5 @@ Covered by core's `runtime-model.test.ts` and engine `profile-subclass.test.ts`.
 - If V8 overflows its own stack inside WebAssembly, QuickJS cannot recover; the
   small QuickJS stack limit keeps its error first, and a host-level failure
   discards the WASM module instance.
+
+S1 shared Connect AI compatibility: the shell client/owner onboarding route forwards `cancel` to shared `chatgpt-cancel`. Unsupported auth SDK cancellation remains an error, not a fake successful sign-out. Existing owner/origin checks and shared readiness status are retained.

package/agents/shared-pieces.md

@@ -0,0 +1,127 @@
+# Shared pieces (Tricia F1)
+
+Tricia keeps its assistant panel, routes, thread models/store and draft/builder
+policy. Engine adapters already use smrt-inference (`engines.md`).
+
+Tool chips use smrt-chat's browser-safe `./tool-summary` entry. The shell module
+is only a policy adapter: `recordLabels: 'generic'` preserves "Checked records"
+and `plainTextSummary` preserves safe free-text labels in saved threads. Shared
+credential, SQL, path and payload guards still apply. Default chat labels do
+not change.
+
+## Test design
+
+| Behavior/invariant | Trigger | Positive | Failure | Actor/context | Executor/transaction | Runtime/dialect | External edge | Level | Command |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Shared tool labels | Both engines and saved-thread replay | Existing words and shared function | JSON, SQL, paths, credentials excluded | Existing owner/thread context | No mutation | Node/browser | Chat browser-safe entry | Unit + existing DOM | app-shell test; chat test |
+| Approval compatibility | Owner requests/decides a risky live action | Original identity, preview, history and one effect | Non-owner, duplicate, invalid action, restart/partial failure | Live verified owner; draft policy stays shell-owned | Shell SQLite + shared authority CAS | Node/SQLite | Runtime authority and chat hold/card | Integration + DOM | app-shell test |
+| Connection compatibility | Welcome/settings connect action | Existing engine readiness and model preference | Non-owner, origin, unavailable engine, upstream failure | Verified current owner | Existing assistant preference writes | Node/browser | Shared ConnectAi + route mount | Integration + DOM | app-shell test |
+
+## Reuse check
+
+MCP `review_smrt_project` reviewed app-shell, chat, app-runtime and smrt-svelte;
+`build_context` architecture query covered tool labels, durable holds/cards and
+engine connection/onboarding. Read the developer-intent index. Name and purpose
+`rg` searches over smrt-ui, smrt-svelte, chat, core, app-runtime, approvals and
+inference found the shared tool-summary, OwnerApprovalAuthority, approval bridge,
+AssistantApprovalCard, ConnectAi and mountConnectAiRoutes. The server exposes
+architecture/model context, but no standalone component/intent/recipe search.
+No parallel parser or tool-label implementation is introduced.
+
+## Compatibility gaps closed
+
+Onboarding GET delegates readiness to `mountConnectAiRoutes.GET`, backed by
+inference's `createAgentCliService` and locked-command preflight, like the
+cookbook host. Tricia adds its onboarding preference and safe version/account
+presentation; those fields never decide readiness. Its browser `ToolInfo` reuses
+the shared ConnectAiState tool shape rather than maintaining a reduced copy.
+Only successful preflight says Ready in this app (with the version when known).
+A signed-in CLI that cannot start remains unselectable with its fixed reason.
+The real fixture-backed route test verifies ready → broken locked command,
+GET/configuration/status refusal, no path disclosure and no billing fallback.
+Both mounted Tricia variants cover the refused state; the existing composer
+selection/sign-out/saved-key flow is retained. Positive DOM snapshots model the
+server's explicit preflight success instead of implying ready from sign-in.
+
+Reuse for this correction: MCP project reviews of app-shell, smrt-svelte and
+template, the intent index, and name/purpose searches found the existing shared
+status handler, inference CLI service, DTO and translated status messages. No new
+component, helper, model, type definition or route file was added.
+
+- Tool words: generic `_list`/`_search`/`_get` results stay "Checked records";
+  arbitrary safe saved summary text remains readable. Both are chat options.
+- Durable holds: Tricia has no expiry. Runtime's explicit `nonExpiring` option
+  requires a store advertising `supportsNonExpiring`; the canonical store still
+  refuses it. The legacy single-tenant storage adapter retains all rows and ids,
+  translates accepted/executing/completed states and uses database CAS rather
+  than a process-local in-flight set. No schema change or data migration.
+- Waits: chat's `observeAssistantApproval` waits for a host-completed result;
+  it cannot decide, consume or execute. Runtime `wait({ settled: true })`
+  observes pending/approved/executing until terminal. Abort/timeout retain rows.
+- Approval UI: the shared card's optional host-authorized presentation retains
+  the heading, Waiting/Approved wording, timestamps, errors, disabled controls
+  and callbacks. Its `detail` snippet carries shell-owned builder/code/draft
+  previews and the publish retry link; that policy stays in Tricia.
+- Connection UI: `presentation="compact"` retains Claude Code + ChatGPT on
+  Welcome, Codex under Advanced in Settings, version/account text, existing
+  legal/advanced links, success messages and auto-selection after a login the
+  page started. Optional `modelState`/`chooseModel` use the existing shell
+  model-preference routes. One shared request/poll/abort lifecycle handles both
+  presentations; the browser-safe `./connect-ai/client` exports the pure words.
+- Connection routes: `allowUnconfiguredApiSelection` preserves choosing API
+  without a key; `includeSignOutConfirmation` preserves the old response.
+  Both default off. The shell maps its established JSON endpoints to the
+  shared actions, retains owner/origin checks, model validation, Fresh/Skip
+  and sign-out preference policy. No assistant route/thread replacement.
+
+## New-file reuse evidence
+
+`src/lib/server/approval-store.ts` is the only new production helper file.
+MCP review/context and `rg` approval/owner/hold/storage/legacy/tenant searches
+found runtime's existing `OwnerApprovalStore` extension seam but no adapter
+for Tricia's `approvals` schema. It implements that seam over the existing
+`ApprovalCollection`; decision, consumption, result bounds and waiting reuse the
+shared authority. The legacy model remains solely for installed storage and its
+saved generated API contract. `approval-store.test.ts` and
+`components/shared-pieces.dom.test.ts` introduce only test-local fixtures and
+exercise the real shared exports. No new component/model/route/tool file.
+
+Hindsight recall was attempted for `package:app-shell`; the configured tool
+reported offline. Canonical adapter documentation is retained here instead.
+
+Template definitions can exceed the shared plain-envelope nesting and 128 KB
+limits. The adapter passes the validated action and preview as inert JSON (the existing
+column contracts), and opts into a 4 MB envelope budget for the shell's bounded
+HTTP/template input plus preview. Shared default limits remain unchanged.
+The only root config edit removes the stale raw-pixel allowance for the old
+card's removed screen-reader CSS; the shared card uses button accessible names.
+
+
+The nested draft-preview regression fails before the JSON-envelope adapter and
+passes after it: field defaults may themselves contain nested JSON and must
+remain visible exactly as reviewed. The shared authority does not interpret
+that host policy data or relax its plain-data depth guard.
+
+
+The old publish-review flow also depends on exact decision-button text. The
+shared Button historically inserts a spacer before its label. MCP review on
+smrt-ui and name/purpose searches for Button label/whitespace/text contracts
+found no opt-out. Its additive `labelWhitespace="trim"` option preserves the
+old shell text; the default `preserve` output is tested unchanged for buttons
+and links. The shared approval card alone opts into trimming. This is the
+small additional owning-package edit in `smrt-ui` (Button plus its existing
+golden tests); no new component/helper/model file is added.
+
+
+C4 OpenAI follow-up: shared Connect AI now lists Codex after recommended ChatGPT
+in welcome and settings, preserving the same preflight-backed Tricia handler,
+model preference and composer refresh. DOM expectations retain real ready status
+and assert the shared order instead of the superseded settings-only disclosure.
+Codex containment is owned by inference (`agents/engines.md`), never a shell shim.
+
+`pnpm test` first runs `svelte-kit sync`: the DOM suite needs the generated
+`.svelte-kit/tsconfig.json` even when Turbo restores only built output. A cold
+checkout without that config otherwise fails in dependency optimization before
+any component test runs (Rolldown's runtime cannot resolve `node:module`).
+The test script prepares the config for both the Node and DOM suites; it does
+not depend on a preceding uncached build.

package/dist/engine/app-runtime.d.ts

@@ -71,6 +71,13 @@ export declare class AppRuntime {
     }>;
     /** A consistent copy of app.db in snapshots/, made with VACUUM INTO. */
     snapshot(kind: string): Promise<string>;
+    /**
+     * A consistent, standalone copy of app.db at `path` (VACUUM INTO: one
+     * statement, so it sees a single committed state, and it needs no -wal or
+     * -shm file next to it). Refuses a path that exists. The host calls it with
+     * no change running and no call in flight.
+     */
+    copyTo(path: string): Promise<string>;
     /** Delete migrate/schema snapshots taken before `beforeMs` (clean up). */
     pruneSnapshots(beforeMs: number): number;
     private mcp;

package/dist/engine/app-runtime.js

@@ -3,8 +3,8 @@
 //
 // Migrations here are SQLite-shaped (RENAME/DROP COLUMN, VACUUM INTO,
 // pragma_table_info). Postgres is future work.
-import { mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
 import { ObjectRegistry, planRuntimeModelDDL, registerRuntimeModel, } from '@happyvertical/smrt-core';
 import { MCPGenerator } from '@happyvertical/smrt-core/generators/mcp';
 import { APIGenerator } from '@happyvertical/smrt-core/generators/rest';
@@ -157,6 +157,16 @@ export class AppRuntime {
                 await exec(`ALTER TABLE ${q(step.table)} RENAME COLUMN ${q(up ? step.from : step.to)} TO ${q(up ? step.to : step.from)}`);
                 break;
             case 'archiveTable':
+                // Undoing a removal puts the archived table back. A model that was
+                // defined again since leaves an EMPTY table of that name (undoing a
+                // define keeps its table): drop it so the original, with its rows,
+                // can return. A table with rows is never dropped; the rename then
+                // fails and says so.
+                if (!up &&
+                    (await this.tableExists(tx, step.table)) &&
+                    (await tx.query(`SELECT 1 FROM ${q(step.table)} LIMIT 1`)).rows
+                        .length === 0)
+                    await exec(`DROP TABLE ${q(step.table)}`);
                 await exec(`ALTER TABLE ${q(up ? step.table : step.archivedAs)} RENAME TO ${q(up ? step.archivedAs : step.table)}`);
                 break;
             case 'dropColumn':
@@ -167,7 +177,10 @@ export class AppRuntime {
                     await exec(`ALTER TABLE ${q(step.table)} DROP COLUMN ${q(step.column)}`);
                 }
                 else {
-                    await exec(`ALTER TABLE ${q(step.table)} ADD COLUMN ${q(step.column)} ${sqlType(step.type)}`);
+                    // Undoing an add keeps its column, so a field added again after the
+                    // removal is still there: put the archived values back into it.
+                    if (!(await this.columnTypes(tx, step.table)).has(step.column))
+                        await exec(`ALTER TABLE ${q(step.table)} ADD COLUMN ${q(step.column)} ${sqlType(step.type)}`);
                     await exec(`UPDATE ${q(step.table)} SET ${q(step.column)} = (SELECT value FROM _archive a WHERE a.version = ? AND a.tbl = ? AND a.col = ? AND a.record_id = ${q(step.table)}.${q(step.key)})`, [m.version, step.table, step.column]);
                     await exec(`DELETE FROM _archive WHERE version = ? AND tbl = ? AND col = ?`, [m.version, step.table, step.column]);
                 }
@@ -293,6 +306,20 @@ export class AppRuntime {
             pruneMethodSnapshots(join(this.dataDir, 'snapshots'));
         return file;
     }
+    /**
+     * A consistent, standalone copy of app.db at `path` (VACUUM INTO: one
+     * statement, so it sees a single committed state, and it needs no -wal or
+     * -shm file next to it). Refuses a path that exists. The host calls it with
+     * no change running and no call in flight.
+     */
+    async copyTo(path) {
+        if (typeof path !== 'string' || !isAbsolute(path))
+            throw new AppError('copyTo needs an absolute path');
+        if (existsSync(path))
+            throw new AppError(`${path} already exists`);
+        await this.db.query(`VACUUM INTO '${path.replace(/'/g, "''")}'`);
+        return path;
+    }
     /** Delete migrate/schema snapshots taken before `beforeMs` (clean up). */
     pruneSnapshots(beforeMs) {
         return pruneMigrationSnapshots(join(this.dataDir, 'snapshots'), Number(beforeMs));

package/dist/engine/commands.d.ts

@@ -46,6 +46,18 @@ export type Command = {
  | {
     type: 'undo';
     version?: number;
+}
+/**
+ * Undo every version after `version` (an ancestor of the current one) in one
+ * command, newest first. It needs approval when any of them has a
+ * `convertColumn` step, decided by the host from the stored versions.
+ * `from` pins the version the caller saw as current; the host refuses if the
+ * app has moved on.
+ */
+ | {
+    type: 'undoTo';
+    version: number;
+    from?: number;
 } | {
     type: 'cleanUp';
     keep: number;
@@ -90,5 +102,16 @@ export declare function overwritesOnUndo(step: {
 }): boolean;
 /** Static risk of a command. `undo` is decided by the host from the stored version. */
 export declare function isRiskyCommand(cmd: Command): boolean;
+/**
+ * Which commands change the app's definition, tables or history. A frozen host
+ * (see `HostOptions.frozen`) refuses every one of them; only `exportTemplate`
+ * reads. It is a total `Record` so that a new command cannot be added without
+ * deciding which side it is on.
+ */
+export declare const STRUCTURAL_COMMANDS: Readonly<Record<CommandType, boolean>>;
+/** True unless the command is known to be read-only (an unknown type counts as structural). */
+export declare function isStructuralCommand(cmd: {
+    type?: unknown;
+}): boolean;
 /** Generated app tools that delete records need approval. */
 export declare function isRiskyTool(name: string): boolean;

package/dist/engine/commands.js

@@ -24,6 +24,35 @@ export function isRiskyCommand(cmd) {
         return Object.values(cmd.data?.definition?.models ?? {}).some((m) => Object.keys(m?.methods ?? {}).length > 0);
     return false;
 }
+/**
+ * Which commands change the app's definition, tables or history. A frozen host
+ * (see `HostOptions.frozen`) refuses every one of them; only `exportTemplate`
+ * reads. It is a total `Record` so that a new command cannot be added without
+ * deciding which side it is on.
+ */
+export const STRUCTURAL_COMMANDS = {
+    defineModel: true,
+    addField: true,
+    hideField: true,
+    renameField: true,
+    removeField: true,
+    changeFieldType: true,
+    removeModel: true,
+    addMethod: true,
+    enableRecipe: true,
+    undo: true,
+    undoTo: true,
+    cleanUp: true,
+    exportTemplate: false,
+    importTemplate: true,
+};
+/** True unless the command is known to be read-only (an unknown type counts as structural). */
+export function isStructuralCommand(cmd) {
+    const type = cmd?.type;
+    return !(typeof type === 'string' &&
+        Object.hasOwn(STRUCTURAL_COMMANDS, type) &&
+        STRUCTURAL_COMMANDS[type] === false);
+}
 /** Generated app tools that delete records need approval. */
 export function isRiskyTool(name) {
     return /_delete$/.test(name);

package/dist/engine/draft.d.ts

@@ -0,0 +1,31 @@
+export declare const DRAFT_MARKER_FILE = ".smrt-draft.json";
+export interface DraftMarker {
+    kind: 'smrt-app-draft';
+    format: 1;
+    /** The live data directory this draft was copied from (real path). */
+    liveDir: string;
+    /** The live version the draft started from. */
+    baseVersion: number;
+    createdAt: string;
+}
+/** A path as the file system sees it; the plain resolved path while it does not exist. */
+export declare function realDir(p: string): string;
+export declare function sameDir(a: string, b: string): boolean;
+/** The marker of a draft directory, or null for an ordinary (live) one. */
+export declare function readDraftMarker(dataDir: string): DraftMarker | null;
+/** Engine-internal: nothing outside the engine may make a directory a draft. */
+export declare function writeDraftMarker(dataDir: string, liveDir: string, baseVersion: number): DraftMarker;
+/** True when `inner` is `outer` or lies under it. */
+export declare function isInside(inner: string, outer: string): boolean;
+/**
+ * Where a new draft may go: a path that does not exist yet, whose parent does
+ * (or can), that is neither the live directory nor inside it nor contains it
+ * (a discard deletes the whole draft directory, so it must never reach live).
+ */
+export declare function checkDraftPath(draftDir: string, liveDir: string): string;
+/**
+ * Delete a draft directory. Only a directory that holds the draft marker (so
+ * one the engine made), is not a symlink and does not contain the live
+ * directory it names. Nothing else is ever removed.
+ */
+export declare function removeDraftDirectory(dataDir: string): void;

package/dist/engine/draft.js

@@ -0,0 +1,88 @@
+// Drafts: a draft is a second app host over a COPY of the live data, in its own
+// directory next to the live one. The directory carries a marker file that only
+// the engine writes; it is what makes a directory a draft (and therefore what
+// allows `autoApprove`, and what lets a discard delete it).
+import { existsSync, lstatSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { EngineError } from "./errors.js";
+export const DRAFT_MARKER_FILE = '.smrt-draft.json';
+/** A path as the file system sees it; the plain resolved path while it does not exist. */
+export function realDir(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+export function sameDir(a, b) {
+    return realDir(a) === realDir(b);
+}
+/** The marker of a draft directory, or null for an ordinary (live) one. */
+export function readDraftMarker(dataDir) {
+    const file = join(dataDir, DRAFT_MARKER_FILE);
+    if (!existsSync(file))
+        return null;
+    let m;
+    try {
+        m = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        throw new EngineError(`${DRAFT_MARKER_FILE} in ${dataDir} is unreadable; remove the draft directory`, 'refused');
+    }
+    if (m?.kind !== 'smrt-app-draft' ||
+        m.format !== 1 ||
+        typeof m.liveDir !== 'string' ||
+        !Number.isInteger(m.baseVersion))
+        throw new EngineError(`${DRAFT_MARKER_FILE} in ${dataDir} is not a draft marker`, 'refused');
+    return m;
+}
+/** Engine-internal: nothing outside the engine may make a directory a draft. */
+export function writeDraftMarker(dataDir, liveDir, baseVersion) {
+    const marker = {
+        kind: 'smrt-app-draft',
+        format: 1,
+        liveDir: realDir(liveDir),
+        baseVersion,
+        createdAt: new Date().toISOString(),
+    };
+    writeFileSync(join(dataDir, DRAFT_MARKER_FILE), JSON.stringify(marker), {
+        flag: 'wx',
+    });
+    return marker;
+}
+/** True when `inner` is `outer` or lies under it. */
+export function isInside(inner, outer) {
+    const a = realDir(inner);
+    const b = realDir(outer);
+    return a === b || a.startsWith(b.endsWith(sep) ? b : b + sep);
+}
+/**
+ * Where a new draft may go: a path that does not exist yet, whose parent does
+ * (or can), that is neither the live directory nor inside it nor contains it
+ * (a discard deletes the whole draft directory, so it must never reach live).
+ */
+export function checkDraftPath(draftDir, liveDir) {
+    const abs = resolve(draftDir);
+    const target = join(realDir(dirname(abs)), abs.slice(dirname(abs).length));
+    if (isInside(target, liveDir) || isInside(liveDir, target))
+        throw new EngineError('the draft directory must be separate from the live data directory', 'refused');
+    if (existsSync(abs))
+        throw new EngineError(`${abs} already exists`, 'refused');
+    return abs;
+}
+/**
+ * Delete a draft directory. Only a directory that holds the draft marker (so
+ * one the engine made), is not a symlink and does not contain the live
+ * directory it names. Nothing else is ever removed.
+ */
+export function removeDraftDirectory(dataDir) {
+    const marker = readDraftMarker(dataDir);
+    if (!marker)
+        throw new EngineError(`${dataDir} is not a draft directory, so it is not removed`, 'refused');
+    if (lstatSync(dataDir).isSymbolicLink())
+        throw new EngineError(`${dataDir} is a symlink; not removed`, 'refused');
+    if (isInside(marker.liveDir, dataDir))
+        throw new EngineError(`${dataDir} contains the live data directory; not removed`, 'refused');
+    rmSync(dataDir, { recursive: true, force: true });
+}