runlist 0.0.0 → 0.94.2

package/assets/contracts/source-editing-v1.md

@@ -0,0 +1,232 @@
+# Source editing v1
+
+`src/source-editor.mjs` is the shared local core for an existing-plan narrative
+editing loop. It supports unambiguous legacy plans and valid native v1 plans,
+flags, and decisions. It does not itself start a web server or change existing
+domain CLI writers. Trusted adapters may opt into configured legacy document
+types with `legacyTypes` and allow read-only unconfigured/untyped sources with
+`allowUnconfiguredRead`. These are host options, never browser request fields.
+Prompts stay excluded; frontmatter and history protections apply to every type.
+The working document application in `src/app.mjs` supplies a
+trusted local human adapter and consumes this core.
+
+## Actor and authority
+
+The trusted local host constructs `createSourceEditor({config, authenticate,
+authorize})`. Both callbacks are required and synchronous; asynchronous
+authentication can happen at the host boundary before calling the core, with
+the callback resolving a verified, revocable session from server-owned state.
+The factory/config/callbacks/test hooks are never request data. This is an
+in-process boundary, not protection against arbitrary code with filesystem
+access.
+
+`authenticate(context)` returns `{kind:'human'|'agent', id, label?, session_id?}`.
+An agent requires its actual session ID. The core never reads the launching
+process's identity from environment variables and ignores an actor supplied in
+the request. A human browser session remains a human even when an agent started
+the server. A browser adapter must authenticate its own session and
+protect mutation requests against cross-site/unauthorized access.
+
+`authorize({actor, action, path})` verifies authority against trusted runtime
+policy. It returns `{allowed:true}` for an authorized human; an authorized agent
+also requires a nonempty `grant_id`. The adapter must verify that the grant is
+current, binds the actor/session and selected checkout/path, permits the exact
+action, and has not expired or been revoked. A grant reference in Markdown is
+evidence to look up, never authority by itself. The core rechecks identity and
+policy after waiting for save locks, and policy again before source publication.
+The receipt attributes the operation to the verified actor and initial grant.
+
+Actions are `read`, `save`, `undo`, `read-draft`, `write-draft`, `discard-draft`,
+`inspect-operation`, and `settle-operation`. Drafts and receipts are additionally
+bound to their owner. Agents include their session in that binding. Inspecting,
+settling, or undoing another actor's operation is not supported by this v1 API.
+
+Future domain operations for rulings, delegation, resolution, lifecycle, task
+allocation, relationships, and migration must use separate action permissions.
+An agent ruling requires a verified delegation permitting that specific ruling,
+not merely permission to edit narrative. Recommendations or accepted awareness
+do not create execution authority. Those writers append shared provenance to
+native metadata through domain operations; this API cannot edit those fields.
+
+## Source, revisions, and conflicts
+
+`read(context,{path})` returns `{path,source,revision,type,editable,diagnostics}`.
+`revision` is `sha256:<64 lowercase hex>` over the exact UTF-8 bytes. It is not a
+Git commit, timestamp, frontmatter `updated`, or inferred current revision.
+CRLF, Unicode, unknown metadata, tables, fences, links, comments, and attachments
+are preserved because the core writes the supplied source without serialization.
+Invalid/unsupported records remain readable and draftable, with `editable:false`.
+The core accepts valid UTF-8 documents up to 8 MiB, without NUL bytes.
+
+`save(context,{path,operationId,expectedRevision,source})` requires an exact base
+revision and a caller-generated lowercase UUID v4. Frontmatter, lifecycle
+`Version History` sections, and the sequence of stable native item anchors must
+remain byte-identical/identity-identical. Narrative and existing task text or
+checkboxes may change. New/removal/reordering of anchored items belongs to future
+domain operations. Every native result is validated before publication. No
+source serializer drops unknown fields or silently repairs invalid metadata.
+
+A stale save throws `SourceEditError` with `code:'revision-conflict'` and
+`details:{expectedRevision,currentRevision,currentSource}`. The application keeps
+the draft, displays base/draft/current source and diff, and asks the user to
+review a merge or reload. It submits a new operation ID against the explicitly
+reviewed current revision. The core does not silently merge, retry a stale save
+against a new revision, or choose a timestamp winner. Read/modify/save is a
+compare-and-swap operation under the existing atomic-mutation path locks.
+
+Configured Markdown roots authorize paths. Symlink sources, escapes, and
+unmanaged types are rejected. A save also locks the canonical CLI ownership
+record and checks its generation before publication. Corrupt ownership or a
+claim held by another actor blocks saving. A human browser does not borrow the
+launching agent's claim; the owner coordinates/releases it through the CLI.
+Even a dead claim is not implicitly taken over by this API. An agent may save
+its own claimed plan with verified edit authority. Saves never claim, release,
+archive, run lifecycle hooks, repair references, stage Git, or commit Git.
+
+Trusted checkout adapters may opt into `allowStageEdits:true`. This permits only
+a plan's `ships:` field to change alongside narrative edits; all other envelope
+bytes, lifecycle history and stable item identities remain protected. Stage
+values are checked against the configured vocabulary, with an unset choice
+allowed. Generic editor adapters retain the byte-identical frontmatter default.
+The same save request, receipts, claims, revision checks and recovery path apply.
+Compensating undo restores the retained exact before-image, including its prior
+stage, without validating that old value as a new stage assignment.
+
+## Durable operations and repair
+
+Before replacing source, the core durably writes a private `prepared` receipt
+containing the operation ID, request kind, path, actor/grant, timestamp, exact
+before/after source and revisions, and optional `undoOf`. The canonical file is
+then atomically replaced with its existing mode and its directory synchronized.
+Finally the receipt becomes `committed`. A successful result contains the
+operation ID/state, resulting revision, actor/grant, and affected files.
+
+The same operation ID with identical owner/path/kind/base/source (or undo target)
+returns the retained outcome and does not write source again. Different payload
+reuse is `operation-reused`. A replay also reports `currentRevision`, which may
+have changed since the historical save; the host rereads before editing further.
+
+After a crash, a prepared receipt is reconciled against current source:
+
+| Current source | Result |
+| --- | --- |
+| Exact after-image | Mark committed/recovered; do not write source again. |
+| Exact before-image | The original owner may retry the original request; a different operation is blocked as pending. |
+| Neither image | Report `repair-required`; preserve all images and current source, write nothing to source. |
+
+This is content-generation recovery. It cannot prove which external writer
+published identical bytes, or reconstruct a missing/corrupt local receipt.
+New saves inspect pending receipts for that document before obscuring their
+publication evidence. Source/durability errors after preparation retain the
+receipt rather than blindly rolling source back over a later external edit.
+
+`inspectOperation(context,{operationId})` returns the retained images and current
+revision to the authorized owner. After explicit inspection,
+`settleOperation(context,{operationId,expectedRevision,disposition:'leave-current'})`
+checks that revision and leaves source untouched. It records `committed` for
+the after-image, `not-applied` for the before-image, or `settled-unknown` for a
+third generation. Unknown is never relabeled success/failure. The settled
+operation cannot be retried to write; further reviewed edits use a new ID.
+Malformed state requires manual inspection and is never silently reset. These
+receipts are separate from existing move/lifecycle transaction manifests and
+are inspected through this API, not `doctor --transactions`.
+
+The existing locking and filesystem authorization are cooperative local
+controls. Uncooperative filesystem writes can still race the final checks and
+rename; descriptor-relative I/O is not implemented. Do not describe this as a
+filesystem security boundary or a cross-clone transaction. A lost receipt or
+a checkout moved to a new local path needs explicit recovery review.
+
+## Draft recovery
+
+`putDraft(context,{path,draftId,expectedDraftRevision,baseSource,baseRevision,source})`
+stores a private draft, including the exact base snapshot for a later three-way
+review. The base source must match its revision, but need not be the current
+source; autosaving a stale draft never overwrites the document. Use `null` for a
+new draft's expected revision. Later writes require the returned draft revision,
+so two tabs cannot silently replace each other's recovery data.
+
+`readDraft(context,{path,draftId})` returns the owner's draft and `stale` when the
+canonical source differs from its base. It never applies the draft automatically.
+`discardDraft(context,{path,draftId,expectedDraftRevision})` durably replaces it
+with a body-free tombstone after explicit discard. A discarded ID can be used
+again with expected revision `null`. Saves do not implicitly delete drafts;
+the host clears them only after receiving/verifying the committed outcome.
+Draft persistence survives host reload/disconnection after the core acknowledges
+the draft. The plan app also keeps browser recovery snapshots before its disk
+autosave acknowledges, and retains pending save/undo operation IDs across reload.
+Missing, moved, or deleted canonical files require manual
+inspection of local state in this first version; no create/rename recovery API
+is provided yet.
+
+State lives under the checkout's `.runlist/editor/` (or existing legacy state
+directory), in owner-scoped draft files and an operation ledger. Files are
+created with mode 0600 and directories with 0700; Windows uses its normal user
+filesystem access controls. State may not traverse symlinks. In a Git checkout,
+storage must be ignored and untracked before any body/before-image is persisted;
+the core does not edit ignore rules. This storage is local, not shared record
+history. No automatic expiry discards recovery data. Cleanup/retention controls
+and a disk-wide draft inventory UI remain further work; the first app discovers
+its browser recovery entries for each selected plan.
+
+## Compensating undo
+
+`undo(context,{path,operationId,undoOf,expectedRevision})` creates a new receipt
+and save operation referencing a retained committed operation. The requester
+must own the original receipt and have current undo authority. The expected
+revision must equal both the current file and the original result. The new
+source reverses that operation's changes; its own exact before/after images and
+actor are retained. If anything changed subsequently, undo reports a conflict
+and requires explicit review. It does not merge over later edits or replay
+claims, hooks, reference repairs, migrations, or Git operations. Undoing the
+compensating operation is a redo with the same revision protections.
+
+The first application exposes the reviewed diff, Save, preserved draft,
+conflict review, and Undo through these operations. Git commit, sharing across
+clones, lifecycle actions, and record migrations remain distinct operations.
+
+## Local document adapter
+
+`runlist app [document] [--port <port>]` selects the configured checkout at startup
+and binds only to `127.0.0.1`. A random access capability in the printed URL
+fragment establishes a separate human browser session. The fragment is removed
+after connection. Sessions use a port-scoped HttpOnly/SameSite=Strict cookie,
+expire after twelve hours, and can be revoked with Disconnect. The adapter uses
+the local OS user identity, not an agent session inherited from the environment.
+This is a local capability, not a remote multi-user login service.
+
+API mutations require the authenticated cookie, exact allowed local Origin,
+and the session's random CSRF token. Host checks reject DNS-rebinding hosts;
+cross-origin API requests are refused. Static content has a restrictive CSP
+and no external scripts/styles. Markdown is escaped and unsafe link schemes
+are refused. No browser request can select a new repository/config, inject an
+actor/policy, release a claim, or start a lifecycle/domain operation. The adapter
+homes configured hubs, plans and documents in a paged library. A hub is the
+organizing document older guidance calls a runlist; its ordered child plans
+live on that same document. Coordination, ordered and roadmap hubs are shapes
+of this concept, not separate required container levels. Only
+unambiguous configured narratives or valid native records are editable; untyped
+and unsupported sources remain read only. Private prompts, excluded corpora and
+generated indexes stay outside this adapter. Domain record views retain separate
+action scopes.
+
+The browser persists recovery data before Save/Undo requests, retries the same
+payload/operation kind after an uncertain acknowledgement, and exposes retained
+before/after/current evidence for explicit leave-current settlement. It does not
+discard an interrupted operation merely because a request failed. Concurrent
+source conflicts preserve the draft and require explicit merged-draft review
+against the current revision. Saves/undo freeze the workspace while in flight
+so a response cannot silently replace typing entered during the request.
+
+
+The default document view edits supported Markdown blocks inline. It retains
+raw source for untouched blocks, comments, and gaps; line-diff publication
+preserves their original line endings. Enter and slash/plus menus create
+blocks, task controls change existing checkboxes, and selected text supports
+basic formatting. Code edits as plain text. Tables, nested lists, unclosed
+fences, and unsupported block syntax have an explicit Markdown fallback.
+Managed lifecycle history is read only in the block view. New/removal/reordering
+of native anchors still belongs to domain operations; the core remains the
+final validator. Draft undo/redo is distinct from compensating Undo save.
+Inline changes autosave only the private draft; reviewed Save publishes source.
+Pasted/dropped content is inserted as text, never authored HTML.

package/assets/opencode/plugin.js

@@ -0,0 +1,162 @@
+// runlist's OpenCode integration. Installed by `runlist install opencode`, which
+// copies this file (with a version banner prepended) to the OpenCode plugin
+// directory, where OpenCode auto-discovers it — it globs
+// `{plugin,plugins}/*.{ts,js}` under `.opencode/` and the global config dir, so
+// no `opencode.json` edit is needed.
+//
+// TWO CONSTRAINTS, both load-bearing:
+//
+//  1. EXACTLY ONE EXPORT. OpenCode treats every export of a plugin module as a
+//     plugin factory and throws `Plugin export is not a function` on anything
+//     that isn't one — so an exported helper wouldn't just be untidy, it would
+//     be *called* as a second plugin. Helpers stay module-local.
+//
+//  2. Only a deliberate guard denial may throw. OpenCode awaits hooks inside
+//     the chat request, so every other failure degrades to a no-op.
+//
+// Runs under Bun inside the OpenCode process. Node builtins only, no deps.
+
+import { execFile } from 'node:child_process';
+
+// The primer is a nicety; identity is a correctness invariant. They are split
+// across two hooks deliberately: `shell.env` is stable API, while
+// `experimental.chat.system.transform` may be renamed by OpenCode. If it is,
+// priming stops and ownership keeps working — the failure lands on the half
+// that can afford it.
+const PRIMER_TTL_MS = 60_000;
+const PRIMER_TIMEOUT_MS = 5_000;
+
+function cliExecutables() {
+  return process.platform === 'win32' ? ['runlist.cmd', 'dotmd.cmd'] : ['runlist', 'dotmd'];
+}
+
+// Runs the CLI and resolves its trimmed stdout, or '' on any failure. `input`,
+// when given, is written to the child's stdin.
+function runCli(directory, args, input = null) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = value => { if (!settled) { settled = true; resolve(value); } };
+    const candidates = cliExecutables();
+    const attempt = index => {
+      if (index >= candidates.length) { done(''); return; }
+      try {
+        const child = execFile(candidates[index], args, {
+          cwd: directory,
+          timeout: PRIMER_TIMEOUT_MS,
+          windowsHide: true,
+          // Node refuses to execFile a `.cmd` without a shell (EINVAL since the
+          // 2024 batch-file fix), and npm installs the CLI on Windows as one.
+          // The arguments are fixed strings, never user input.
+          shell: process.platform === 'win32',
+          env: { ...process.env, NO_COLOR: '1' },
+        }, (error, stdout) => {
+          if (error?.code === 'ENOENT') attempt(index + 1);
+          else done(error ? '' : (stdout ?? '').trim());
+        });
+        child.stdin?.on('error', () => {});
+        if (input !== null) child.stdin?.end(input);
+        else child.stdin?.end();
+      } catch { attempt(index + 1); }
+    };
+    attempt(0);
+  });
+}
+
+// OpenCode runs no Claude Code hooks. Evaluate recognized prompt reads before
+// the tool so opt-in strict mode can block them. Its V1 before hook cannot
+// return model context, so ordinary warnings are appended to the result.
+const PROMPT_FILE = /(^|[\\/])prompts[\\/]\S*\.md\b/;
+
+function guardPayload(tool, args) {
+  if (tool === 'read' && typeof args?.filePath === 'string' && PROMPT_FILE.test(args.filePath)) {
+    return { tool_name: 'Read', tool_input: { file_path: args.filePath } };
+  }
+  if (tool === 'bash' && typeof args?.command === 'string' && PROMPT_FILE.test(args.command)) {
+    return { tool_name: 'Bash', tool_input: { command: args.command } };
+  }
+  return null;
+}
+
+export default async function runlistOpencodePlugin({ directory }) {
+  // Keyed by session so a subagent session primes independently, the way
+  // SubagentStart does under Claude Code.
+  const primers = new Map();
+  const guardDecisions = new Map();
+
+  async function guardFor(tool, args) {
+    const payload = guardPayload(tool, args);
+    if (!payload) return null;
+    const raw = await runCli(directory, ['guard'], JSON.stringify(payload));
+    return raw ? JSON.parse(raw)?.hookSpecificOutput ?? null : null;
+  }
+
+  async function primerFor(sessionId) {
+    const key = sessionId ?? '';
+    const cached = primers.get(key);
+    // Refreshed on a TTL rather than cached for the session's life: OpenCode
+    // rebuilds the system prompt every turn, so a once-only push would reach
+    // only the first request — and a never-refreshed one would keep announcing
+    // a pending prompt this session already consumed.
+    if (cached && Date.now() - cached.at < PRIMER_TTL_MS) return cached.text;
+    const text = await runCli(directory, ['hud']);
+    primers.set(key, { text, at: Date.now() });
+    return text;
+  }
+
+  return {
+    'tool.execute.before': async (input, output) => {
+      let refusal = null;
+      try {
+        const decision = await guardFor(input?.tool, output?.args);
+        if (input?.callID && decision) guardDecisions.set(input.callID, decision);
+        if (decision?.permissionDecision === 'deny') {
+          if (input?.callID) guardDecisions.delete(input.callID);
+          refusal = decision.permissionDecisionReason;
+        }
+      } catch { /* a missing/broken guard must not fail the chat turn */ }
+      if (refusal) throw new Error(`[runlist] ${refusal}`);
+    },
+    // Ownership identity. OpenCode sets no session-id variable of its own, and
+    // `OPENCODE_PID` — what runlist falls back to without this plugin — names the
+    // OpenCode *process*, so every session in one TUI shares it and can release
+    // the others' plans. This is the only place the real session id is
+    // available to a tool shell.
+    'shell.env': async (input, output) => {
+      try {
+        if (input?.sessionID) {
+          output.env.RUNLIST_SESSION_ID = `opencode:${input.sessionID}`;
+          // Legacy name, kept for an older CLI (before 0.77.0) still on PATH.
+          output.env.DOTMD_SESSION_ID = `opencode:${input.sessionID}`;
+        }
+        // The OpenCode server process hosts the session and outlives every tool
+        // shell, so it is the process whose liveness answers "is this claim's
+        // owner still there?" — `runlist doctor --claims` probes exactly this.
+        output.env.RUNLIST_SESSION_PID = String(process.pid);
+        output.env.DOTMD_SESSION_PID = String(process.pid);
+      } catch { /* never break a shell over this */ }
+    },
+
+    // The guard's warnings, appended after the call ran. A `deny` from the
+    // guard is ignored here: the call has already happened, so there is
+    // nothing left to refuse.
+    'tool.execute.after': async (input, output) => {
+      try {
+        if (typeof output?.output !== 'string') return;
+        const decision = input?.callID ? guardDecisions.get(input.callID) : null;
+        if (input?.callID) guardDecisions.delete(input.callID);
+        const note = (decision ?? await guardFor(input?.tool, input?.args))?.additionalContext;
+        if (typeof note === 'string' && note) output.output += `\n\n${note}`;
+      } catch { /* a guard failure never touches the tool result */ }
+    },
+
+    // Session priming — the equivalent of the SessionStart hook that runs
+    // `runlist hud` under Claude Code. Silent outside a runlist repo (hud prints
+    // nothing and exits 0), so this is inert in unrelated projects.
+    'experimental.chat.system.transform': async (input, output) => {
+      try {
+        const text = await primerFor(input?.sessionID);
+        if (text) output.system.push(text);
+      } catch { /* priming is best-effort */ }
+    },
+  };
+}