orbitmap 0.4.2 → 0.4.4

package/dist/paths.js

@@ -1,6 +1,6 @@
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { basename, dirname, join, resolve } from 'node:path';
 /** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). */
 export const ORBITMAP_DIR = '.orbitmap';
 /**
@@ -12,6 +12,28 @@ export const ORBITMAP_DIR = '.orbitmap';
 export const CONFIG_FILENAME = 'config.json';
 /** Filename of the machine-local secret store (`~/.orbitmap/credentials.json`). */
 export const CREDENTIALS_FILENAME = 'credentials.json';
+/**
+ * Filename of the gitignored, machine-specific link file (`<project>/.orbitmap/link.json`).
+ *
+ * Duplicated from `workspace-resolve.ts`'s `LINK_FILE` rather than imported: that module
+ * sits above this one, and this is a leaf.
+ */
+const LINK_FILENAME = 'link.json';
+/**
+ * The one directory holding documents, in **both** modes (IN-rwb5qu).
+ *
+ * Cloud mode: `<project>/.orbitmap/docs/` is the download cache. Local mode: the same
+ * `docs/` inside the workspace directory is the domain data itself — and for the usual
+ * in-project workspace (`<project>/.orbitmap`) that is literally the same path. Hence one
+ * name here rather than one per layer: there is exactly ONE copy of a document on disk,
+ * globally, with **no per-area subdirectories** (the data model does not record a
+ * document's home area, so the directory tree must not pretend it does).
+ */
+export const DOCS_DIR = 'docs';
+/** Pre-v2 local-workspace name of {@link DOCS_DIR}; migrated away by `LocalStore.migrate()`. */
+export const LEGACY_DOCUMENTS_DIR = 'documents';
+/** Cache bookkeeping inside {@link DOCS_DIR}; written in cloud mode only. */
+export const DOC_CACHE_MANIFEST = '.manifest.json';
 let homeCache;
 /**
  * The resolved OrbitMap home, memoised.
@@ -141,22 +163,165 @@ export function findProjectConfigFiles(startDir = process.cwd()) {
     const found = [];
     const globals = new Set(globalConfigPaths().map(canonical));
     const homeStop = canonical(homedir());
+    const seenFiles = new Set();
+    const seenStarts = new Set();
+    // Directories whose walk-up still has to run: `startDir` first, then any workspace root a
+    // `link.json` back-pointer found along the way names (see the doc comment above).
+    const queue = [resolve(startDir)];
+    while (queue.length > 0) {
+        const start = queue.shift();
+        if (seenStarts.has(canonical(start)))
+            continue;
+        seenStarts.add(canonical(start));
+        let dir = start;
+        for (;;) {
+            const orbitmapDir = join(dir, ORBITMAP_DIR);
+            const candidate = join(orbitmapDir, CONFIG_FILENAME);
+            if (existsSync(candidate) &&
+                !globals.has(canonical(candidate)) &&
+                !isOrbitMapHomeDir(orbitmapDir)) {
+                const key = canonical(candidate);
+                if (!seenFiles.has(key)) {
+                    seenFiles.add(key);
+                    found.push(candidate);
+                }
+            }
+            // An out-of-tree area cannot reach its workspace root by walking up; its machine-local
+            // `link.json` says where the root is, so the walk hops there and continues rather than
+            // ending with `agent`/`mode`/`workspace` unresolved (IS-ktfg5z).
+            const pointer = workspacePointer(orbitmapDir);
+            if (pointer && !seenStarts.has(canonical(pointer)))
+                queue.push(pointer);
+            if (canonical(dir) === homeStop)
+                break;
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return found;
+}
+/**
+ * The nearest directory at or above `startDir` that owns an `.orbitmap/` — the project (or
+ * workspace) root the doc cache and the `.gitignore` entries belong to. `undefined` when the
+ * walk finds none.
+ *
+ * The same walk and the same guards as {@link findProjectConfigFiles}, for the same reasons:
+ * an OrbitMap *home* is never a project (a relocated or mis-`$HOME`-ed `~/.orbitmap` sits on
+ * the walk path as an ordinary ancestor), and nothing above the user's home is that user's
+ * project. Only the *directory* is required to exist here — a project that has never had a
+ * `config.json` still owns its `.orbitmap/link.json` or `.orbitmap/docs/`.
+ *
+ * This is what replaces the doc cache's old `join('.orbitmap', 'docs')`, which resolved
+ * against `process.cwd()` with no walk-up at all and therefore scattered a fresh copy of
+ * every document into every subdirectory a command happened to run from.
+ *
+ * **One workspace = one directory = one `.orbitmap`.** The walk is not a search for any
+ * `.orbitmap` that happens to look like a workspace: it stops at the first ancestor that
+ * declares one ({@link declaresWorkspace}) and returns it, or follows an explicit
+ * back-pointer ({@link workspacePointer}) when the area lives outside the tree. Climbing
+ * past the first declaration used to hand the deepest directory to the *furthest* ancestor
+ * declaring a workspace — by construction not its owner — so two workspaces side by side
+ * under a third pooled their documents into the outermost one's flat `<slug>.md` namespace
+ * and overwrote each other (IS-8hv2wn).
+ */
+export function findProjectOrbitMapDir(startDir = process.cwd()) {
+    const globals = new Set(globalConfigPaths().map(canonical));
+    const homeStop = canonical(homedir());
+    let nearest;
     let dir = resolve(startDir);
     for (;;) {
         const orbitmapDir = join(dir, ORBITMAP_DIR);
-        const candidate = join(orbitmapDir, CONFIG_FILENAME);
-        if (existsSync(candidate) &&
-            !globals.has(canonical(candidate)) &&
-            !isOrbitMapHomeDir(orbitmapDir)) {
-            found.push(candidate);
+        if (existsSync(orbitmapDir) &&
+            !isOrbitMapHomeDir(orbitmapDir) &&
+            !globals.has(canonical(join(orbitmapDir, CONFIG_FILENAME)))) {
+            nearest ??= dir;
+            // A back-pointer wins outright: this directory has been told, in writing, where its
+            // workspace lives, so there is nothing left to search for.
+            const pointer = workspacePointer(orbitmapDir);
+            if (pointer)
+                return pointer;
+            // The FIRST declaring config is the owner. Climbing further would hand `startDir`
+            // to whichever unrelated ancestor happens to declare a workspace too — by
+            // definition not the one that owns it (IS-8hv2wn).
+            if (declaresWorkspace(orbitmapDir))
+                return dir;
         }
         if (canonical(dir) === homeStop)
-            return found;
+            break;
         const parent = dirname(dir);
         if (parent === dir)
-            return found;
+            break;
         dir = parent;
     }
+    return nearest;
+}
+/** Parse a JSON file into a plain object, or `undefined` when it is missing/unreadable. */
+function readJsonObject(file) {
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf-8'));
+        if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+            return undefined;
+        return raw;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The workspace **directory** this `.orbitmap/` points at, when it points at one elsewhere.
+ *
+ * An area directory living outside the workspace tree cannot reach the workspace root by
+ * walking up — there is nothing above it but unrelated directories. `init` therefore writes
+ * `{"workspace": "<path>"}` into that area's own machine-local `link.json` (the same field,
+ * the same meaning, as in local mode: *where* the workspace is). Following it is what keeps
+ * such an area sharing the one global `docs/` instead of quietly starting a second copy.
+ *
+ * Accepts either the workspace root or its `.orbitmap/` directory — `resolveWorkspacePath`
+ * hands back the latter for a `workspace.yml`-marked local workspace, so both spellings of
+ * "the workspace is over there" exist in the wild, and both must mean the same directory
+ * here. Relative paths resolve against the link file, exactly as in `resolveWorkspacePath`.
+ */
+function workspacePointer(orbitmapDir) {
+    const link = readJsonObject(join(orbitmapDir, LINK_FILENAME));
+    const target = link?.['workspace'];
+    if (typeof target !== 'string' || !target)
+        return undefined;
+    const resolved = resolve(orbitmapDir, target);
+    return basename(resolved) === ORBITMAP_DIR ? dirname(resolved) : resolved;
+}
+/**
+ * Does this `.orbitmap/` belong to a *workspace* root rather than an area directory?
+ *
+ * The distinction is **location**, not identity. An out-of-tree area marker also carries a
+ * `workspace` field, because it needs the slug for the `X-Orbitmap-Workspace` header and has
+ * no root config to inherit it from — but naming your workspace is not the same as being its
+ * root, and reading it as one gave that directory its own second copy of every document.
+ * A file that pins an `area` is a marker, full stop; a root is what maps `areas` (or names a
+ * workspace without claiming to be an area). Read directly rather than through
+ * `project-config.ts`, which sits above this module.
+ *
+ * `link.json` is deliberately *not* enough on its own: its `workspace` field is a pointer at
+ * a workspace somewhere else (see {@link workspacePointer}) — the opposite of being one. Only
+ * its `areas` map, which lists the out-of-tree areas *of this workspace*, marks a root.
+ */
+function declaresWorkspace(orbitmapDir) {
+    const link = readJsonObject(join(orbitmapDir, LINK_FILENAME));
+    if (isPlainObject(link?.['areas']))
+        return true;
+    const raw = readJsonObject(join(orbitmapDir, CONFIG_FILENAME));
+    if (!raw)
+        return false;
+    if (isPlainObject(raw['areas']))
+        return true;
+    // `typeof null === 'object'` used to make `"areas": null` a workspace root; hence the
+    // explicit shape check above and the `area`-marker exclusion here.
+    return typeof raw['workspace'] === 'string' && typeof raw['area'] !== 'string';
+}
+/** A non-null, non-array object — what an `areas` map has to be to mean anything. */
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 /**
  * Per-field walk-up: hand each project config file, nearest first, to `read` and return the

package/dist/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"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"}

package/dist/project-config.d.ts

@@ -41,11 +41,52 @@ export interface OrbitMapConfig {
     workspace_path?: string;
     /** Name of the agent profile to use — looked up in `~/.orbitmap/credentials.json`. */
     agent?: string;
-    /** Default area slug/id. */
+    /**
+     * Workspace this config belongs to — a workspace **slug or UUID**, never a path (the
+     * *directory* is `workspace_path` / the `link.json` pointer / the marker walk-up).
+     *
+     * Written into the workspace directory's own `.orbitmap/config.json` (schema v2), which is
+     * committable and holds no secrets. Purely declarative here: this field says *which*
+     * workspace the tree belongs to, it does not participate in the workspace-directory ladder.
+     */
+    workspace?: string;
+    /**
+     * Directory → area slug map (schema v2): "the code for area `x` lives in this directory".
+     *
+     * **Keys are relative directory paths, resolved against the parent of the `.orbitmap`
+     * directory that holds this config file** — i.e. against the workspace/project root, not
+     * against the current directory and not against `.orbitmap/` itself. `"."` is that root.
+     * Keys are normalised on read ({@link normalizeAreaPathKey}): backslashes become `/`,
+     * `./` prefixes and trailing slashes are dropped, and an empty result becomes `"."`.
+     *
+     * Values are area slugs.
+     *
+     * **Absolute keys and keys that escape upward (`..`) are rejected**, deliberately: a
+     * directory outside the tree is machine-specific and therefore belongs in the gitignored
+     * `link.json` (see `WorkspaceLink.areas` in `workspace-resolve.ts`), not in a file meant to
+     * be committed and to mean the same thing in every checkout.
+     */
+    areas?: Record<string, string>;
+    /**
+     * Default area slug/id.
+     *
+     * Still read on every rung for back-compat — an existing project config that pins `area`
+     * keeps working unchanged. Schema v2 replaces it with the directory-scoped {@link areas}
+     * map plus a per-area marker config, so `orbitmap init` no longer *writes* this field.
+     */
     area?: string;
     /** @deprecated Legacy secret, read once for migration then dropped. Never written. */
     api_key?: string;
 }
+/**
+ * Canonical form of one {@link OrbitMapConfig.areas} key, or `undefined` when the key is not
+ * a usable relative directory path.
+ *
+ * Normalises what a hand-written (or Windows-written) config may contain — `.\packages\api`,
+ * `packages/api/`, `./` — into one comparable form (`packages/api`, `.`). Rejects absolute
+ * paths and any `..` segment; see {@link OrbitMapConfig.areas} for why.
+ */
+export declare function normalizeAreaPathKey(key: string): string | undefined;
 /**
  * Parse and validate a raw config object (either file) — mistyped fields drop out instead
  * of propagating a garbage value into the resolution ladders. Unknown keys are not

package/dist/project-config.js

@@ -1,5 +1,51 @@
 import { readFileSync } from 'node:fs';
 import { resolveProjectField } from './paths.js';
+/** Matches a Windows drive prefix (`C:`), which `node:path`'s POSIX `isAbsolute` does not —
+ *  an `areas` key is a portable, committable path and must be rejected on every platform. */
+const WINDOWS_DRIVE = /^[a-zA-Z]:/;
+/**
+ * Canonical form of one {@link OrbitMapConfig.areas} key, or `undefined` when the key is not
+ * a usable relative directory path.
+ *
+ * Normalises what a hand-written (or Windows-written) config may contain — `.\packages\api`,
+ * `packages/api/`, `./` — into one comparable form (`packages/api`, `.`). Rejects absolute
+ * paths and any `..` segment; see {@link OrbitMapConfig.areas} for why.
+ */
+export function normalizeAreaPathKey(key) {
+    const slashed = key.replace(/\\/g, '/').trim();
+    if (!slashed)
+        return undefined;
+    if (slashed.startsWith('/') || WINDOWS_DRIVE.test(slashed))
+        return undefined;
+    const segments = slashed.split('/').filter((part) => part.length > 0 && part !== '.');
+    if (segments.some((part) => part === '..'))
+        return undefined;
+    return segments.length === 0 ? '.' : segments.join('/');
+}
+/**
+ * Validate the `areas` map: a plain object of relative-directory → non-empty area slug.
+ *
+ * **Rejected per entry, not per file.** One unusable key (absolute, `..`, non-string value)
+ * must not take the rest of a repository's mapping down with it — the same reasoning as the
+ * per-field validation in {@link parseConfig}. When nothing valid is left the field itself is
+ * dropped, so a ladder sees "not set" rather than an empty map. On a collision (two keys
+ * normalising to the same directory) the first entry wins.
+ */
+function parseAreasMap(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const areas = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (typeof value !== 'string' || !value)
+            continue;
+        const dir = normalizeAreaPathKey(key);
+        if (dir === undefined)
+            continue;
+        if (!(dir in areas))
+            areas[dir] = value;
+    }
+    return Object.keys(areas).length > 0 ? areas : undefined;
+}
 /**
  * Parse and validate a raw config object (either file) — mistyped fields drop out instead
  * of propagating a garbage value into the resolution ladders. Unknown keys are not
@@ -19,6 +65,11 @@ export function parseConfig(raw) {
     }
     if (typeof r['agent'] === 'string' && r['agent'])
         config.agent = r['agent'];
+    if (typeof r['workspace'] === 'string' && r['workspace'])
+        config.workspace = r['workspace'];
+    const areas = parseAreasMap(r['areas']);
+    if (areas)
+        config.areas = areas;
     if (typeof r['area'] === 'string' && r['area'])
         config.area = r['area'];
     if (typeof r['api_key'] === 'string' && r['api_key'])

package/dist/project-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../src/project-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqDjD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ;QAAE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACzF,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACnE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC;QAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC;QAAE,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAEpF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;sFACsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAQ,EACR,WAAmB,OAAO,CAAC,GAAG,EAAE;IAEhC,MAAM,GAAG,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG;QACR,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAuC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QACxE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}
+{"version":3,"file":"project-config.js","sourceRoot":"","sources":["../src/project-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqFjD;6FAC6F;AAC7F,MAAM,aAAa,GAAG,YAAY,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7E,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC;IACtF,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAE7D,OAAO,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAEpF,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;QAC1E,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK;YAAE,SAAS;QAClD,MAAM,GAAG,GAAG,oBAAoB,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,IAAI,CAAC,CAAC,GAAG,IAAI,KAAK,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC1C,CAAC;IAED,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IACvD,MAAM,CAAC,GAAG,GAA8B,CAAC;IACzC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAElC,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ;QAAE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IACzF,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,OAAO;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,gBAAgB,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACnE,MAAM,CAAC,cAAc,GAAG,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,OAAO,CAAC;QAAE,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC;IAC5E,IAAI,OAAO,CAAC,CAAC,WAAW,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,WAAW,CAAC;QAAE,MAAM,CAAC,SAAS,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,IAAI,KAAK;QAAE,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IAChC,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,SAAS,CAAC;QAAE,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC;IAEpF,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;sFACsF;AACtF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,KAAQ,EACR,WAAmB,OAAO,CAAC,GAAG,EAAE;IAEhC,MAAM,GAAG,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1F,OAAO,GAAG;QACR,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAuC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE;QACxE,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/work-log.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Work log — the vocabulary, the reference → target dispatch and the `--log` batch parser.
+ *
+ * A work log entry targets exactly ONE of a task, an intent or a mission (intent IN-pjrs6e).
+ * Tasks were the only target until now, so `orbitmap log` assumed one; this module is the
+ * single place that decides which of the three a reference means, so the decision cannot
+ * drift between `orbitmap log` and the `--log` batches carried by `intent update`,
+ * `mission update` and `mission status`.
+ *
+ * Two rules the API owns and the CLI must NOT reimplement:
+ *
+ * - **`status_change` is server-authored.** The server knows `from` and `to` and composes
+ *   that line itself; the Agent API rejects the type from a client. It is therefore absent
+ *   from {@link WORK_LOG_TYPES} and rejected here with an explanation rather than forwarded
+ *   for a 422.
+ * - **A status transition must carry at least one entry.** That is enforced server-side
+ *   (422) — the CLI does not pre-check it, because it cannot know whether the status is
+ *   actually changing without an extra round trip. {@link describeWorkLogRequirement} turns
+ *   the server's rejection into something the caller can act on.
+ *
+ * References travel verbatim: `/intents/{id_or_number}/logs` and
+ * `/missions/{id_or_number}/logs` resolve display numbers server-side (see
+ * `tests/reference-passthrough.test.ts`), so nothing here rewrites an identifier — it only
+ * reads the prefix to pick the endpoint.
+ */
+/**
+ * The log types a CLIENT may author (`WorkLog::CALLER_TYPES` server-side).
+ *
+ * Deliberately narrower than the column vocabulary: `status_change` is missing on purpose
+ * (see the module comment). Also deliberately narrower than the vibe types — the two groups
+ * do not overlap, mirroring `log_work` in orbitmap-mcp.
+ */
+export declare const WORK_LOG_TYPES: readonly ["note", "code_change", "decision", "blocker"];
+export type WorkLogType = (typeof WORK_LOG_TYPES)[number];
+/** Log types only the server may write. Rejected here with an explanation, never forwarded. */
+export declare const SERVER_AUTHORED_LOG_TYPES: readonly ["status_change"];
+/** Vibe-only types: valid for `orbitmap vibe log`, rejected by the work-log endpoints. */
+export declare const VIBE_ONLY_TYPES: readonly ["discovery", "exploration", "fix"];
+/** The three objects a work log entry can attach to. */
+export declare const WORK_LOG_TARGETS: readonly ["task", "intent", "mission"];
+export type WorkLogTarget = (typeof WORK_LOG_TARGETS)[number];
+/** One entry of a `--log` batch, shaped as the API's `logs[]` elements. */
+export interface WorkLogEntry {
+    type: string;
+    content: string;
+}
+/**
+ * One entry as the API RETURNS it, which is a wider shape than the `logs[]`
+ * elements we send: `show` embeds the stored row, not the request body.
+ */
+export interface WorkLogRecord {
+    id: string;
+    type: string;
+    content: string;
+    metadata?: Record<string, unknown> | null;
+    created_at: string | null;
+}
+/**
+ * Render the `work_logs` a detail payload embeds.
+ *
+ * The API returns them oldest-first so they read as a narrative; this preserves
+ * that order rather than imposing a newest-first view. Returns an empty string
+ * when there is nothing to show, so callers can print unconditionally.
+ */
+export declare function formatWorkLogs(logs: readonly WorkLogRecord[] | undefined): string;
+/** The human-readable list of types, used verbatim in every message and in `--help`. */
+export declare const WORK_LOG_TYPE_LIST: string;
+/**
+ * Which object a `orbitmap log` reference names.
+ *
+ * A prefixed display number answers it outright (`TS-` → task, `IN-` → intent, `MS-` →
+ * mission). A bare uuid or bare object code carries no type at all, so it stays a **task** —
+ * the behaviour every existing caller has — unless `--target` says otherwise. That flag is
+ * the only way to log against an intent or a mission by uuid, and it is rejected when it
+ * contradicts a prefix rather than silently overriding it.
+ */
+export declare function resolveWorkLogTarget(ref: string, explicit?: string): WorkLogTarget;
+/**
+ * Validate a single work-log type, with the two wrong-vocabulary cases named rather than
+ * lumped into "invalid". `undefined` is valid: the API defaults an absent type to `note`.
+ */
+export declare function assertWorkLogType(type: string, label?: string): void;
+/**
+ * Parse a repeated `--log <type>:<content>` flag into the API's `logs[]` array, preserving
+ * the order the flags were given in — the entries read as a narrative, so their order is
+ * part of the payload.
+ *
+ * Split on the FIRST colon only: log content is prose and routinely contains colons
+ * (`--log decision:"chose 3 FKs: one per target"` must keep `chose 3 FKs: one per target`).
+ */
+export declare function parseLogFlags(values: readonly string[] | undefined, flag?: string): WorkLogEntry[];
+/**
+ * Turn the API's "a status change needs a reason" 422 into an actionable instruction.
+ *
+ * The server rejects a status transition that carries no `logs[]`, and nothing is written at
+ * all when it does — so the caller has to re-run the command, and the message has to say
+ * with what. Every other error is returned untouched, so an unrelated 422 (a bad status
+ * value, a missing field) still prints exactly what the server said.
+ */
+export declare function describeWorkLogRequirement(error: unknown, context: {
+    entity: 'intent' | 'mission';
+    statusChanged: boolean;
+    logCount: number;
+}): unknown;

package/dist/work-log.js

@@ -0,0 +1,181 @@
+/**
+ * Work log — the vocabulary, the reference → target dispatch and the `--log` batch parser.
+ *
+ * A work log entry targets exactly ONE of a task, an intent or a mission (intent IN-pjrs6e).
+ * Tasks were the only target until now, so `orbitmap log` assumed one; this module is the
+ * single place that decides which of the three a reference means, so the decision cannot
+ * drift between `orbitmap log` and the `--log` batches carried by `intent update`,
+ * `mission update` and `mission status`.
+ *
+ * Two rules the API owns and the CLI must NOT reimplement:
+ *
+ * - **`status_change` is server-authored.** The server knows `from` and `to` and composes
+ *   that line itself; the Agent API rejects the type from a client. It is therefore absent
+ *   from {@link WORK_LOG_TYPES} and rejected here with an explanation rather than forwarded
+ *   for a 422.
+ * - **A status transition must carry at least one entry.** That is enforced server-side
+ *   (422) — the CLI does not pre-check it, because it cannot know whether the status is
+ *   actually changing without an extra round trip. {@link describeWorkLogRequirement} turns
+ *   the server's rejection into something the caller can act on.
+ *
+ * References travel verbatim: `/intents/{id_or_number}/logs` and
+ * `/missions/{id_or_number}/logs` resolve display numbers server-side (see
+ * `tests/reference-passthrough.test.ts`), so nothing here rewrites an identifier — it only
+ * reads the prefix to pick the endpoint.
+ */
+import { OrbitMapAPIError } from './errors.js';
+import { OBJECT_PREFIXES, objectPrefix } from './id-resolve.js';
+/**
+ * The log types a CLIENT may author (`WorkLog::CALLER_TYPES` server-side).
+ *
+ * Deliberately narrower than the column vocabulary: `status_change` is missing on purpose
+ * (see the module comment). Also deliberately narrower than the vibe types — the two groups
+ * do not overlap, mirroring `log_work` in orbitmap-mcp.
+ */
+export const WORK_LOG_TYPES = ['note', 'code_change', 'decision', 'blocker'];
+/** Log types only the server may write. Rejected here with an explanation, never forwarded. */
+export const SERVER_AUTHORED_LOG_TYPES = ['status_change'];
+/** Vibe-only types: valid for `orbitmap vibe log`, rejected by the work-log endpoints. */
+export const VIBE_ONLY_TYPES = ['discovery', 'exploration', 'fix'];
+/** The three objects a work log entry can attach to. */
+export const WORK_LOG_TARGETS = ['task', 'intent', 'mission'];
+/** Display-number prefix → the object a work log entry would attach to. */
+const PREFIX_TARGETS = Object.freeze({
+    TS: 'task',
+    IN: 'intent',
+    MS: 'mission',
+});
+/**
+ * Render the `work_logs` a detail payload embeds.
+ *
+ * The API returns them oldest-first so they read as a narrative; this preserves
+ * that order rather than imposing a newest-first view. Returns an empty string
+ * when there is nothing to show, so callers can print unconditionally.
+ */
+export function formatWorkLogs(logs) {
+    if (!logs || logs.length === 0)
+        return '';
+    const lines = logs.map((log) => {
+        const stamp = log.created_at ? log.created_at.slice(0, 16).replace('T', ' ') : '';
+        // Content is free text and frequently multi-line; indent continuation lines
+        // so an entry stays visually one block under its header.
+        const body = log.content.split('\n').join('\n    ');
+        return `  [${log.type}] ${stamp}\n    ${body}`;
+    });
+    return `\nWork log (${logs.length}):\n${lines.join('\n')}`;
+}
+/** The human-readable list of types, used verbatim in every message and in `--help`. */
+export const WORK_LOG_TYPE_LIST = WORK_LOG_TYPES.join(', ');
+/**
+ * Which object a `orbitmap log` reference names.
+ *
+ * A prefixed display number answers it outright (`TS-` → task, `IN-` → intent, `MS-` →
+ * mission). A bare uuid or bare object code carries no type at all, so it stays a **task** —
+ * the behaviour every existing caller has — unless `--target` says otherwise. That flag is
+ * the only way to log against an intent or a mission by uuid, and it is rejected when it
+ * contradicts a prefix rather than silently overriding it.
+ */
+export function resolveWorkLogTarget(ref, explicit) {
+    const prefix = objectPrefix(ref);
+    const fromPrefix = prefix ? PREFIX_TARGETS[prefix] : undefined;
+    if (prefix && !fromPrefix) {
+        throw unsupportedPrefix(prefix, ref);
+    }
+    if (explicit === undefined) {
+        return fromPrefix ?? 'task';
+    }
+    const target = explicit.trim();
+    if (!WORK_LOG_TARGETS.includes(target)) {
+        throw OrbitMapAPIError.validation(`Invalid --target "${explicit}". Valid: ${WORK_LOG_TARGETS.join(', ')}`);
+    }
+    if (fromPrefix && fromPrefix !== target) {
+        throw OrbitMapAPIError.validation(`--target ${target} contradicts "${ref.trim()}", which is a ${fromPrefix} reference. ` +
+            `Drop --target, or pass the ${target}'s own id.`);
+    }
+    return target;
+}
+/** `IS-`/`ID-`/`VB-` and friends: a real object, but not one a work log entry can attach to. */
+function unsupportedPrefix(prefix, ref) {
+    const kind = OBJECT_PREFIXES[prefix];
+    const base = `Work log entries attach to tasks, intents and missions. "${ref.trim()}" is ` +
+        `${kind ? `a ${kind}` : 'not one of them'}`;
+    return OrbitMapAPIError.validation(kind === 'vibe'
+        ? `${base} — use \`orbitmap vibe log --content "…"\` instead.`
+        : `${base} — pass a TS-, IN- or MS- reference instead.`);
+}
+/**
+ * Validate a single work-log type, with the two wrong-vocabulary cases named rather than
+ * lumped into "invalid". `undefined` is valid: the API defaults an absent type to `note`.
+ */
+export function assertWorkLogType(type, label = 'log type') {
+    if (WORK_LOG_TYPES.includes(type)) {
+        return;
+    }
+    if (SERVER_AUTHORED_LOG_TYPES.includes(type)) {
+        throw OrbitMapAPIError.validation(`The ${label} "${type}" is written by the server on a status change — a client cannot ` +
+            `author it. Valid: ${WORK_LOG_TYPE_LIST}.`);
+    }
+    if (VIBE_ONLY_TYPES.includes(type)) {
+        throw OrbitMapAPIError.validation(`Log type "${type}" belongs to vibes, not work logs. Use ` +
+            `\`orbitmap vibe log --content "…" --type ${type}\`, or pick one of: ` +
+            `${WORK_LOG_TYPE_LIST}.`);
+    }
+    throw OrbitMapAPIError.validation(`Invalid ${label} "${type}". Valid: ${WORK_LOG_TYPE_LIST}`);
+}
+/**
+ * Parse a repeated `--log <type>:<content>` flag into the API's `logs[]` array, preserving
+ * the order the flags were given in — the entries read as a narrative, so their order is
+ * part of the payload.
+ *
+ * Split on the FIRST colon only: log content is prose and routinely contains colons
+ * (`--log decision:"chose 3 FKs: one per target"` must keep `chose 3 FKs: one per target`).
+ */
+export function parseLogFlags(values, flag = '--log') {
+    if (!values || values.length === 0) {
+        return [];
+    }
+    return values.map((raw) => {
+        const separator = raw.indexOf(':');
+        if (separator === -1) {
+            throw OrbitMapAPIError.validation(`Invalid ${flag} value "${raw}" — expected <type>:<content>, e.g. ` +
+                `${flag} decision:"chose 3 FKs over a pivot". Types: ${WORK_LOG_TYPE_LIST}.`);
+        }
+        const type = raw.slice(0, separator).trim();
+        const content = raw.slice(separator + 1).trim();
+        assertWorkLogType(type, `${flag} type`);
+        if (content.length === 0) {
+            throw OrbitMapAPIError.validation(`Empty content in ${flag} "${raw}" — write what happened after the colon, e.g. ` +
+                `${flag} ${type}:"…".`);
+        }
+        return { type, content };
+    });
+}
+/**
+ * Turn the API's "a status change needs a reason" 422 into an actionable instruction.
+ *
+ * The server rejects a status transition that carries no `logs[]`, and nothing is written at
+ * all when it does — so the caller has to re-run the command, and the message has to say
+ * with what. Every other error is returned untouched, so an unrelated 422 (a bad status
+ * value, a missing field) still prints exactly what the server said.
+ */
+export function describeWorkLogRequirement(error, context) {
+    if (!(error instanceof OrbitMapAPIError) || error.status !== 422) {
+        return error;
+    }
+    // Three independent signals, because only the first is guaranteed: the server names the
+    // rejection with its own code (`INTENT_STATUS_LOG_REQUIRED` / `MISSION_STATUS_LOG_REQUIRED`,
+    // observed on the provider), the message says so, or the shape of the call makes it the
+    // only possible reading — a transition was requested and no entry accompanied it.
+    const looksLikeMissingLogs = error.code.endsWith('_STATUS_LOG_REQUIRED') ||
+        /work log/i.test(error.message) ||
+        Object.keys(error.details ?? {}).some((field) => field === 'logs' || field.startsWith('logs.')) ||
+        (context.statusChanged && context.logCount === 0);
+    if (!looksLikeMissingLogs) {
+        return error;
+    }
+    return new OrbitMapAPIError(`${error.message.trim()}\n` +
+        `Changing this ${context.entity}'s status requires at least one work log entry, and ` +
+        `nothing was written. Re-run with --log <type>:<content>, e.g. ` +
+        `--log decision:"why this transition". Types: ${WORK_LOG_TYPE_LIST}.`, error.code, error.status, error.details);
+}
+//# sourceMappingURL=work-log.js.map