orbitmap 0.4.0-next.0 → 0.4.1

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAiBjC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAC,CAAC;AAChD,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,aAAa,CAAC,CAAC;AAEpD,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAmB,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAsB;IACrD,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,SAAS,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;AAChF,CAAC;AAQD,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC;IACjE,MAAM,MAAM,GACV,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAC/B,MAAM,CAAC,OAAO;QACd,sDAAsD,CAAC;IAEzD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GACR,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;QAC5B,MAAM,CAAC,IAAI;QACX,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QAClC,MAAM,CAAC,UAAU,CAAC;IAEpB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,QAAiB,EACjB,WAAoB;IAEpB,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,WAAW,CAAC;AACjE,CAAC;AAED;;;;;GAKG"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EACL,eAAe,EACf,eAAe,EACf,oBAAoB,EACpB,qBAAqB,EACrB,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,WAAW,EACX,yBAAyB,GAE1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAUhE,OAAO,EAAE,yBAAyB,EAA6B,MAAM,qBAAqB,CAAC;AAE3F;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC;AAExC,sEAAsE;AACtE,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAE1D,sFAAsF;AACtF,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,gBAAgB,YAAY,CAAC;AAE/D,+EAA+E;AAE/E;yFACyF;AACzF,KAAK,UAAU,iBAAiB,CAAC,IAAY;IAC3C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAY,CAAC;QACpE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,SAAS,CAAC;QAC7F,OAAO,MAAiC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,IAAa;IACxD,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC1C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;IACrE,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,KAAK,UAAU,aAAa,CAC1B,IAAY,EACZ,KAAqB,EACrB,YAAqB;IAErB,MAAM,IAAI,GACR,CAAC,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAC/B,CAAC,YAAY,IAAI,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,iBAAiB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3F,EAAE,CAAC;IAEL,MAAM,MAAM,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IACpD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC;IACzB,MAAM,CAAC,gBAAgB,CAAC,GAAG,sBAAsB,CAAC;IAElD,MAAM,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACtC,CAAC;AAED,+EAA+E;AAE/E,IAAI,wBAAwB,GAAG,KAAK,CAAC;AAErC,8DAA8D;AAC9D,MAAM,UAAU,4BAA4B;IAC1C,wBAAwB,GAAG,KAAK,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,KAAK,UAAU,mBAAmB,CAAC,MAAsB;IACvD,IAAI,CAAC,MAAM,CAAC,cAAc,IAAI,CAAC,CAAC,IAAI,sBAAsB;QAAE,OAAO;IACnE,IAAI,wBAAwB;QAAE,OAAO;IACrC,wBAAwB,GAAG,IAAI,CAAC;IAEhC,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC;IACjC,MAAM,QAAQ,GAAG,oBAAoB,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,qBAAqB,EAAE,CAAC;IAE1C,IAAI,CAAC;QACH,IAAI,SAAS;YAAE,MAAM,gBAAgB,CAAC,oBAAoB,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACpF,OAAO,MAAM,CAAC,OAAO,CAAC;QAEtB,MAAM,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;QACjD,sFAAsF;QACtF,IAAI,SAAS,IAAI,QAAQ,KAAK,SAAS;YAAE,MAAM,aAAa,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;QAE/E,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,IAAI,GAAG,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,OAAO,CAAC,IAAI,CACV,gDAAgD,SAAS,GAAG,IAAI,QAAQ;gBACtE,GAAG,eAAe,EAAE,cAAc,oBAAoB,MAAM;gBAC5D,6CAA6C,CAChD,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,oFAAoF;QACpF,wBAAwB,GAAG,KAAK,CAAC;QACjC,IAAI,CAAC,SAAS;YAAE,OAAO,CAAC,+DAA+D;QAEvF,sFAAsF;QACtF,4DAA4D;QAC5D,MAAM,CAAC,OAAO,GAAG,SAAS,CAAC;QAC3B,OAAO,CAAC,IAAI,CACV,yDAAyD,QAAQ,IAAI;YACnE,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,wBAAwB;YACjF,6EAA6E;YAC7E,+EAA+E,CAClF,CAAC;IACJ,CAAC;AACH,CAAC;AAED;iEACiE;AACjE,MAAM,CAAC,KAAK,UAAU,UAAU;IAC9B,MAAM,GAAG,GAAG,MAAM,iBAAiB,CAAC,oBAAoB,EAAE,CAAC,CAAC;IAC5D,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IAEpB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAsB;IAC3D,MAAM,IAAI,GAAG,qBAAqB,EAAE,CAAC;IACrC,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;IAC1D,OAAO,IAAI,CAAC;AACd,CAAC;AAED,mEAAmE;AAEnE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,MAAsB,EACtB,MAAc,OAAO,CAAC,GAAG,EAAE;IAE3B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC;IAC/D,MAAM,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,IAAI,CAAC;AACd,CAAC;AAgBD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,UAA8B,EAAE;IAChE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IACzC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC;IAEtD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,eAAe,CAAC;IAElE,IAAI,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAE7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,KAAK,GACT,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;YAC7B,yBAAyB,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,KAAK;YAC9C,MAAM,CAAC,KAAK;YACZ,oBAAoB,CAAC;QACvB,MAAM,GAAG,CAAC,MAAM,gBAAgB,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC;IACpD,CAAC;IAED,qFAAqF;IACrF,IAAI,CAAC,MAAM;QAAE,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC;IAErC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,uEAAuE,CACxE,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AAC5B,CAAC"}

package/dist/doc-cache.d.ts

@@ -17,7 +17,27 @@ export interface DownloadResult {
 export declare function getCacheDir(): string;
 export declare function readManifest(): Manifest;
 export declare function writeManifest(manifest: Manifest): void;
-export declare function ensureGitignore(): void;
+/**
+ * Append any of `entries` missing from `<cwd>/.gitignore` (creating the file if needed) and
+ * return the entries actually written.
+ *
+ * Idempotent — entries already present are left alone and nothing is written when there is
+ * nothing missing, which is why the return value matters: a caller that announces "added X
+ * to .gitignore" would otherwise say so on every re-run. Reused by `setup-mcp.ts` for
+ * `.mcp.json`, which carries a Bearer token the same way the doc cache and `link.json`
+ * carry no secret but still shouldn't be committed as machine-local state.
+ */
+export declare function ensureGitignore(entries?: string[], cwd?: string): string[];
+/**
+ * True when `.gitignore` already has a blanket `.orbitmap/` entry from before ADR 0002.
+ * Callers use this to warn instead of silently leaving the project's config untracked.
+ *
+ * A trailing comment (`.orbitmap/ # doc cache`) and surrounding whitespace are stripped
+ * before matching; negations (`!.orbitmap/config.json`) are not — a user who wrote one has
+ * already solved the problem this warning is about, so treating the blanket line as
+ * shadowing would be a false alarm.
+ */
+export declare function gitignoreShadowsProjectConfig(cwd?: string): boolean;
 export declare function downloadDocument(client: WorkspaceAdapter, idOrSlug: string): Promise<DownloadResult>;
 export declare function cleanupCache(availableDocSlugs: string[]): {
     removed: string[];

package/dist/doc-cache.js

@@ -22,19 +22,79 @@ export function writeManifest(manifest) {
     mkdirSync(dirname(manifestPath), { recursive: true });
     writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
 }
-export function ensureGitignore() {
-    const gitignorePath = '.gitignore';
-    const entry = '.orbitmap/';
-    if (existsSync(gitignorePath)) {
-        const content = readFileSync(gitignorePath, 'utf-8');
-        if (content.includes(entry))
-            return;
-        const separator = content.endsWith('\n') ? '' : '\n';
-        writeFileSync(gitignorePath, `${content}${separator}${entry}\n`, 'utf-8');
-    }
-    else {
-        writeFileSync(gitignorePath, `${entry}\n`, 'utf-8');
+/**
+ * Entries this cache needs ignored when no more specific list is given: the download cache
+ * itself and the local-workspace pointer file. Deliberately **not** a blanket `.orbitmap/`
+ * — `<project>/.orbitmap/config.json` (ADR 0002) lives in the same directory and is meant
+ * to be committed, so ignoring the whole directory would silently swallow it.
+ */
+const DEFAULT_GITIGNORE_ENTRIES = ['.orbitmap/docs/', '.orbitmap/link.json'];
+/**
+ * Append any of `entries` missing from `<cwd>/.gitignore` (creating the file if needed) and
+ * return the entries actually written.
+ *
+ * Idempotent — entries already present are left alone and nothing is written when there is
+ * nothing missing, which is why the return value matters: a caller that announces "added X
+ * to .gitignore" would otherwise say so on every re-run. Reused by `setup-mcp.ts` for
+ * `.mcp.json`, which carries a Bearer token the same way the doc cache and `link.json`
+ * carry no secret but still shouldn't be committed as machine-local state.
+ */
+export function ensureGitignore(entries = DEFAULT_GITIGNORE_ENTRIES, cwd = process.cwd()) {
+    const gitignorePath = join(cwd, '.gitignore');
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+    const existingLines = new Set(existing.split(/\r?\n/).map((line) => line.trim()));
+    const missing = entries.filter((entry) => !existingLines.has(entry));
+    if (missing.length === 0)
+        return [];
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    writeFileSync(gitignorePath, `${existing}${separator}${missing.join('\n')}\n`, 'utf-8');
+    return missing;
+}
+/**
+ * Every `.gitignore` line shape that ignores the whole `.orbitmap/` directory — and
+ * therefore also hides the new, committable `.orbitmap/config.json` (ADR 0002).
+ *
+ * git treats a pattern containing no slash (other than a trailing one) as matching at every
+ * level, so `**​/.orbitmap/` and `.orbitmap/*` are the same blanket in practice as the plain
+ * `.orbitmap/` this CLI used to write.
+ */
+const BLANKET_ORBITMAP_PATTERNS = new Set([
+    '.orbitmap',
+    '.orbitmap/',
+    '.orbitmap/*',
+    '.orbitmap/**',
+    '/.orbitmap',
+    '/.orbitmap/',
+    '/.orbitmap/*',
+    '/.orbitmap/**',
+    '**/.orbitmap',
+    '**/.orbitmap/',
+    '**/.orbitmap/*',
+    '**/.orbitmap/**',
+]);
+/**
+ * True when `.gitignore` already has a blanket `.orbitmap/` entry from before ADR 0002.
+ * Callers use this to warn instead of silently leaving the project's config untracked.
+ *
+ * A trailing comment (`.orbitmap/ # doc cache`) and surrounding whitespace are stripped
+ * before matching; negations (`!.orbitmap/config.json`) are not — a user who wrote one has
+ * already solved the problem this warning is about, so treating the blanket line as
+ * shadowing would be a false alarm.
+ */
+export function gitignoreShadowsProjectConfig(cwd = process.cwd()) {
+    const gitignorePath = join(cwd, '.gitignore');
+    if (!existsSync(gitignorePath))
+        return false;
+    const lines = readFileSync(gitignorePath, 'utf-8').split(/\r?\n/).map(normalizeGitignoreLine);
+    if (lines.some((line) => line === '!.orbitmap/config.json' || line === '!/.orbitmap/config.json')) {
+        return false;
     }
+    return lines.some((line) => BLANKET_ORBITMAP_PATTERNS.has(line));
+}
+/** Strip a trailing `#` comment and surrounding whitespace from one `.gitignore` line. */
+function normalizeGitignoreLine(line) {
+    const withoutComment = line.replace(/(?:^|\s)#.*$/, '');
+    return withoutComment.trim();
 }
 export async function downloadDocument(client, idOrSlug) {
     const response = (await client.getDocument(idOrSlug, 'file'));

package/dist/doc-cache.js.map

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

package/dist/id-resolve.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Prefixed display IDs (`TS-uw9yh5`, `IS-4k2p9q`, …) are what the CLI prints and therefore
+ * what users paste back in. This module is the single place that understands them.
+ *
+ * The Agent API is asymmetric about them: `/issues/{id}`, `/ideas/{id}`, `/intents/{id}` and
+ * `/missions/{id}` resolve a prefixed ID inline, server-side, but **tasks do not** — a task
+ * reference that is not a uuid has to go through `/tasks/by-number/{number}` first, with the
+ * `TS-` prefix stripped. Before this module the CLI patched that around in four copies of the
+ * same two helpers and simply omitted it in eight commands, so the same identifier worked in
+ * `orbitmap task` and 404'd in `orbitmap status`.
+ *
+ * Resolution lives in the adapter layer (see `resolveTaskRef` below and its callers in
+ * `adapters/cloud.ts`), not in the commands: per CLAUDE.md commands never talk to the network
+ * and never reimplement rules, and putting it there means a new task command gets prefixed-ID
+ * support for free instead of having to remember. `LocalAdapter` already resolves every task
+ * reference through `requireTaskFile`, so this brings cloud mode up to the same contract.
+ */
+/** Two-letter prefix → object type, as the Agent API assigns them. */
+export declare const OBJECT_PREFIXES: {
+    readonly TS: "task";
+    readonly IS: "issue";
+    readonly ID: "idea";
+    readonly VB: "vibe";
+    readonly IN: "intent";
+    readonly MS: "mission";
+};
+export type ObjectPrefix = keyof typeof OBJECT_PREFIXES;
+/**
+ * A prefixed display ID or a bare object code — i.e. anything that is NOT a uuid and has to
+ * be resolved by number. Six base-36 characters, optionally behind a two-letter prefix.
+ *
+ * This is the one shared predicate for the number-vs-uuid decision; a uuid is 36 characters
+ * with dashes and can never match, and a value that matches can never be a uuid, so the two
+ * paths are mutually exclusive by construction. Kept byte-identical to the four helper copies
+ * it replaces so no existing input changes meaning.
+ */
+export declare function isObjectNumber(id: string): boolean;
+/** Canonical uuid check, for callers that need the positive form rather than {@link isObjectNumber}. */
+export declare function isUuid(id: string): boolean;
+/**
+ * Drop the two-letter prefix from a display ID, leaving the bare object code. A value with no
+ * prefix (a bare code, or a uuid) is returned unchanged, so this is safe to call on anything.
+ */
+export declare function stripPrefix(id: string): string;
+/** The prefix of a display ID, or `undefined` when there is none. Never mangles the input. */
+export declare function objectPrefix(id: string): ObjectPrefix | undefined;
+/** The subset of the adapter surface {@link resolveTaskRef} needs. */
+export interface TaskNumberLookup {
+    getTaskByNumber(taskNumber: string): Promise<unknown>;
+}
+/**
+ * Turn any task reference — uuid, `TS-uw9yh5` or the bare code `uw9yh5` — into the uuid the
+ * task endpoints expect.
+ *
+ * A uuid costs **no extra request**: it is returned as-is, synchronously in effect, so the
+ * commands that already passed uuids keep their single round trip. Only a by-number reference
+ * pays for the `/tasks/by-number/{n}` lookup, which is the price of the API asymmetry this
+ * works around (see the module comment) and disappears if `/tasks/{id}` ever resolves
+ * prefixed IDs inline the way `/intents/{id}` already does.
+ */
+export declare function resolveTaskRef(ref: string, lookup: TaskNumberLookup): Promise<string>;

package/dist/id-resolve.js

@@ -0,0 +1,87 @@
+import { OrbitMapAPIError } from './errors.js';
+/**
+ * Prefixed display IDs (`TS-uw9yh5`, `IS-4k2p9q`, …) are what the CLI prints and therefore
+ * what users paste back in. This module is the single place that understands them.
+ *
+ * The Agent API is asymmetric about them: `/issues/{id}`, `/ideas/{id}`, `/intents/{id}` and
+ * `/missions/{id}` resolve a prefixed ID inline, server-side, but **tasks do not** — a task
+ * reference that is not a uuid has to go through `/tasks/by-number/{number}` first, with the
+ * `TS-` prefix stripped. Before this module the CLI patched that around in four copies of the
+ * same two helpers and simply omitted it in eight commands, so the same identifier worked in
+ * `orbitmap task` and 404'd in `orbitmap status`.
+ *
+ * Resolution lives in the adapter layer (see `resolveTaskRef` below and its callers in
+ * `adapters/cloud.ts`), not in the commands: per CLAUDE.md commands never talk to the network
+ * and never reimplement rules, and putting it there means a new task command gets prefixed-ID
+ * support for free instead of having to remember. `LocalAdapter` already resolves every task
+ * reference through `requireTaskFile`, so this brings cloud mode up to the same contract.
+ */
+/** Two-letter prefix → object type, as the Agent API assigns them. */
+export const OBJECT_PREFIXES = {
+    TS: 'task',
+    IS: 'issue',
+    ID: 'idea',
+    VB: 'vibe',
+    IN: 'intent',
+    MS: 'mission',
+};
+/**
+ * A prefixed display ID or a bare object code — i.e. anything that is NOT a uuid and has to
+ * be resolved by number. Six base-36 characters, optionally behind a two-letter prefix.
+ *
+ * This is the one shared predicate for the number-vs-uuid decision; a uuid is 36 characters
+ * with dashes and can never match, and a value that matches can never be a uuid, so the two
+ * paths are mutually exclusive by construction. Kept byte-identical to the four helper copies
+ * it replaces so no existing input changes meaning.
+ */
+export function isObjectNumber(id) {
+    return /^([A-Z]{2}-)?[a-z0-9]{6}$/.test(id.trim());
+}
+/** Canonical uuid check, for callers that need the positive form rather than {@link isObjectNumber}. */
+export function isUuid(id) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id.trim());
+}
+/**
+ * Drop the two-letter prefix from a display ID, leaving the bare object code. A value with no
+ * prefix (a bare code, or a uuid) is returned unchanged, so this is safe to call on anything.
+ */
+export function stripPrefix(id) {
+    return id.trim().replace(/^[A-Z]{2}-/, '');
+}
+/** The prefix of a display ID, or `undefined` when there is none. Never mangles the input. */
+export function objectPrefix(id) {
+    const match = id.trim().match(/^([A-Z]{2})-/);
+    const prefix = match?.[1];
+    return prefix && prefix in OBJECT_PREFIXES ? prefix : undefined;
+}
+/** Dig the task uuid out of a `/tasks/by-number/{n}` (or `/tasks/{id}`) response envelope. */
+function taskIdFromEnvelope(response) {
+    const data = response?.data;
+    const task = data?.task ?? data;
+    const id = task?.id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Turn any task reference — uuid, `TS-uw9yh5` or the bare code `uw9yh5` — into the uuid the
+ * task endpoints expect.
+ *
+ * A uuid costs **no extra request**: it is returned as-is, synchronously in effect, so the
+ * commands that already passed uuids keep their single round trip. Only a by-number reference
+ * pays for the `/tasks/by-number/{n}` lookup, which is the price of the API asymmetry this
+ * works around (see the module comment) and disappears if `/tasks/{id}` ever resolves
+ * prefixed IDs inline the way `/intents/{id}` already does.
+ */
+export async function resolveTaskRef(ref, lookup) {
+    const trimmed = ref.trim();
+    if (!isObjectNumber(trimmed))
+        return trimmed;
+    const response = await lookup.getTaskByNumber(stripPrefix(trimmed));
+    const id = taskIdFromEnvelope(response);
+    if (!id) {
+        // The lookup answered but without an id — a contract drift we must not paper over by
+        // sending the unresolved reference on and letting it 404 somewhere less obvious.
+        throw new OrbitMapAPIError(`Could not resolve task \`${trimmed}\` to an id — the API returned no task id for it.`, 'NOT_FOUND', 404);
+    }
+    return id;
+}
+//# sourceMappingURL=id-resolve.js.map

package/dist/id-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-resolve.js","sourceRoot":"","sources":["../src/id-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;;;;;GAgBG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,OAAO;IACX,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,MAAM;IACV,EAAE,EAAE,QAAQ;IACZ,EAAE,EAAE,SAAS;CACL,CAAC;AAIX;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAO,2BAA2B,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;AACrD,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,MAAM,CAAC,EAAU;IAC/B,OAAO,iEAAiE,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,EAAU;IACrC,MAAM,KAAK,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,MAAM,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1B,OAAO,MAAM,IAAI,MAAM,IAAI,eAAe,CAAC,CAAC,CAAE,MAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;AACpF,CAAC;AAOD,8FAA8F;AAC9F,SAAS,kBAAkB,CAAC,QAAiB;IAC3C,MAAM,IAAI,GAAI,QAA+B,EAAE,IAAI,CAAC;IACpD,MAAM,IAAI,GAAI,IAA2B,EAAE,IAAI,IAAI,IAAI,CAAC;IACxD,MAAM,EAAE,GAAI,IAAyB,EAAE,EAAE,CAAC;IAC1C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAW,EACX,MAAwB;IAExB,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IAE7C,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,MAAM,EAAE,GAAG,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,qFAAqF;QACrF,iFAAiF;QACjF,MAAM,IAAI,gBAAgB,CACxB,4BAA4B,OAAO,mDAAmD,EACtF,WAAW,EACX,GAAG,CACJ,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/index.js

@@ -33,13 +33,21 @@ import { intentListCommand, intentShowCommand, intentCreateCommand, intentUpdate
 import { missionListCommand, missionShowCommand, missionCreateCommand, missionUpdateCommand, missionStatusCommand, missionLinkCommand, missionUnlinkCommand, } from './commands/mission.js';
 import { depAddCommand, depRemoveCommand } from './commands/dep.js';
 import { getCommand } from './commands/get.js';
+import { createRequire } from 'node:module';
 import { createAreaCommand } from './commands/create-area.js';
 import { setWorkspaceFlag } from './workspace-resolve.js';
 const program = new Command();
+/**
+ * `--version` reads the real package version instead of a hardcoded literal, which had gone
+ * stale (it still said 0.3.0 two releases later, so `orbitmap --version` lied about what was
+ * installed). `../package.json` resolves to the repo root from both `src/` and `dist/`, and npm
+ * always ships package.json in the tarball regardless of the `files` allow-list.
+ */
+const { version } = createRequire(import.meta.url)('../package.json');
 program
     .name('orbitmap')
     .description('CLI tool for OrbitMap Agent API')
-    .version('0.3.0')
+    .version(version)
     .option('--json', 'Output in JSON format', false)
     .option('--area <id>', 'Area ID or slug to use')
     .option('--workspace <path>', 'Local workspace directory to use (local mode)');
@@ -60,6 +68,9 @@ program
     .option('--workspace <path>', 'Local workspace directory (default: ./.orbitmap)')
     .option('--workspace-name <name>', 'Local workspace name (default: current directory name)')
     .option('--no-skills', 'Skip installing the OrbitMap agent skills')
+    .option('--agent <type>', 'Coding agent to install the skills for: claude, gemini, codex, cursor, windsurf, generic ' +
+    '(default: detected from this directory, or asked)')
+    .option('--global', 'Cloud: write to ~/.orbitmap/config.json instead of ./.orbitmap/config.json')
     .action(async (opts, command) => {
     // `--workspace` also exists as a program-level flag, and Commander binds it there;
     // `optsWithGlobals()` picks it up whichever position it was given in.
@@ -74,6 +85,8 @@ program
         workspace: opts.workspace ?? all['workspace'],
         workspaceName: opts.workspaceName,
         skills: opts.skills,
+        agent: opts.agent,
+        global: opts.global,
     });
 });
 program
@@ -157,14 +170,14 @@ program
     await getCommand(prefixedId, { json: globalOpts.json, area: globalOpts.area });
 });
 program
-    .command('task <id>')
-    .description('Show full task details (UUID or task number)')
+    .command('task <id-or-number>')
+    .description('Show full task details (UUID, TS-prefixed ID, or task number)')
     .action(async (id, _opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await taskCommand(id, { json: globalOpts.json, area: globalOpts.area });
 });
 program
-    .command('task-edit-content <task-id>')
+    .command('task-edit-content <id-or-number>')
     .description('Edit task content (title, description, agent instructions)')
     .option('--title <title>', 'New title')
     .option('--description <text>', 'New description')
@@ -180,14 +193,14 @@ program
     });
 });
 program
-    .command('start [task-id]')
+    .command('start [id-or-number]')
     .description('Start working on a task (auto-pick if no ID given)')
     .action(async (taskId, _opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     await startCommand(taskId, { json: globalOpts.json, area: globalOpts.area });
 });
 program
-    .command('status <task-id> <status>')
+    .command('status <id-or-number> <status>')
     .description('Update task status (backlog, todo, in_progress, in_review, review_changes, done, blocked)')
     .option('--delivery <status>', 'Delivery status: on_branch, merged, released')
     .option('--force', 'Allow done even with unfinished subtasks')
@@ -231,7 +244,7 @@ program
     });
 });
 program
-    .command('subtask <parent-id> <title>')
+    .command('subtask <parent-id-or-number> <title>')
     .description('Create a subtask under a parent task')
     .option('--desc <description>', 'Subtask description')
     .option('--priority <priority>', 'Priority (critical, high, medium, low)')
@@ -247,7 +260,7 @@ program
     });
 });
 program
-    .command('assign <id> [agent-id]')
+    .command('assign <id-or-number> [agent-id]')
     .description('Assign a task, issue, idea, or intent to an agent or user')
     .option('--user-id <id>', 'Assign to a user (by user ID) instead of an agent')
     .option('--type <type>', 'Object type: task, issue, idea, intent (auto-detected from prefixed IDs; default task)')
@@ -261,7 +274,7 @@ program
     });
 });
 program
-    .command('log <task-id> <message>')
+    .command('log <id-or-number> <message>')
     .description('Log work on a task')
     .option('--type <type>', 'Log type: note, code_change, decision, blocker, discovery, exploration, fix', 'note')
     .option('--meta <json>', 'JSON metadata (e.g. \'{"files":["..."]}\')')
@@ -421,7 +434,8 @@ program
 });
 program
     .command('setup-agent')
-    .description('Add OrbitMap instructions to your agent config file')
+    .description('Refresh the OrbitMap agent instructions/skills, or add another agent type ' +
+    '(`init` already installs them once)')
     .option('--agent <type>', 'Agent type: claude, gemini, codex, cursor, windsurf, generic')
     .action(async (opts) => {
     await setupAgentCommand({ agent: opts.agent });
@@ -1067,7 +1081,7 @@ const dep = program
     .command('dep')
     .description('Manage task dependencies');
 dep
-    .command('add <task-id> <target-task-id>')
+    .command('add <id-or-number> <target-id-or-number>')
     .description('Add a dependency between tasks')
     .option('--type <type>', 'Dependency type: depends_on, related', 'depends_on')
     .option('--note <text>', 'Optional note for the dependency')
@@ -1081,7 +1095,7 @@ dep
     });
 });
 dep
-    .command('remove <task-id> <target-task-id>')
+    .command('remove <id-or-number> <target-id-or-number>')
     .description('Remove a dependency between tasks')
     .option('--type <type>', 'Dependency type to remove: depends_on, related')
     .action(async (taskId, targetTaskId, opts, cmd) => {