orbitmap 0.3.0 → 0.4.1

package/dist/config.js

@@ -1,34 +1,217 @@
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-const CONFIG_DIR = join(homedir(), '.orbitmap');
-const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
-export async function loadConfig() {
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { CONFIG_FILENAME, credentialsPath, globalConfigReadPath, globalConfigWritePath, ORBITMAP_DIR, } from './paths.js';
+import { parseConfig, resolveProjectConfigField, } from './project-config.js';
+import { loadAgentProfile, saveAgentProfile } from './oauth.js';
+export { resolveProjectConfigField } from './project-config.js';
+/**
+ * Version stamped into every config file this module writes (ADR 0002). It is also the
+ * migration gate: a global config already carrying this version has been through
+ * {@link migrateGlobalConfig} and is never re-examined, on this run or any later one.
+ */
+export const CURRENT_SCHEMA_VERSION = 1;
+/** Agent profile a pre-ADR-0002 global `api_key` is migrated into. */
+const LEGACY_AGENT_PROFILE = 'default';
+/**
+ * The only supported Agent API host. Every default in the CLI resolves here — do not
+ * hardcode a base URL anywhere else, and never ship a hosting-provider origin
+ * (it lets callers bypass whatever fronts the public domain).
+ */
+export const DEFAULT_API_HOST = 'https://app.orbitmap.ai';
+/** Default Agent API base URL: {@link DEFAULT_API_HOST} + the `/api/agent` prefix. */
+export const DEFAULT_API_URL = `${DEFAULT_API_HOST}/api/agent`;
+// ── Raw file I/O ────────────────────────────────────────────────────────────
+/** The file's JSON object exactly as written, or `undefined` when it is missing,
+ *  unreadable or not a JSON object. Used to preserve keys this version does not know. */
+async function readRawConfigFile(file) {
     try {
-        const raw = await readFile(CONFIG_FILE, 'utf-8');
-        return JSON.parse(raw);
+        const parsed = JSON.parse(await readFile(file, 'utf-8'));
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        return parsed;
     }
     catch {
-        return {};
+        return undefined;
+    }
+}
+/**
+ * Write JSON to `file` atomically: a sibling temp file plus a rename, which is atomic on
+ * every filesystem the CLI targets. `loadConfig()` performs a write as a side effect of the
+ * ADR 0002 migration, so two CLI processes starting at once can both reach this — with a
+ * plain `writeFile` the loser could observe (and persist) a half-written file.
+ */
+async function writeJsonAtomic(file, data) {
+    await mkdir(dirname(file), { recursive: true });
+    const temp = `${file}.${process.pid}.tmp`;
+    await writeFile(temp, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+    await rename(temp, file);
+}
+/**
+ * Merge `patch` into whatever `file` already holds and write the result.
+ *
+ * Two rules, both about not destroying data the CLI did not write:
+ *
+ * - **Unknown keys survive.** The on-disk object is the base; only the keys `patch`
+ *   actually sets are overwritten. A key from a future version (or a hand-written note)
+ *   is never erased by a save — least of all by the migration, which is triggered by what
+ *   the user experiences as a read.
+ * - **`api_key` never survives.** It is the one key this module actively removes: ADR 0002
+ *   moved it into `credentials.json`, and leaving a copy behind in a committable-shaped
+ *   file is the failure mode the ADR exists to end.
+ *
+ * `fallbackFile` (optional) is read when `file` itself does not exist yet — used when the
+ * global config is read from the legacy `~/.orbitmap` location but written to a relocated
+ * one, so the relocated copy inherits the legacy file's unknown keys.
+ */
+async function mergeIntoFile(file, patch, fallbackFile) {
+    const base = (await readRawConfigFile(file)) ??
+        (fallbackFile && fallbackFile !== file ? await readRawConfigFile(fallbackFile) : undefined) ??
+        {};
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value !== undefined)
+            merged[key] = value;
     }
+    delete merged['api_key'];
+    merged['schema_version'] = CURRENT_SCHEMA_VERSION;
+    await writeJsonAtomic(file, merged);
 }
-export async function saveConfig(config) {
-    await mkdir(CONFIG_DIR, { recursive: true });
-    await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+// ── Global config ───────────────────────────────────────────────────────────
+let globalMigrationAttempted = false;
+/** Reset the once-per-process migration latch. Tests only. */
+export function resetConfigMigrationForTests() {
+    globalMigrationAttempted = false;
+}
+/**
+ * One-time migration of the global config to {@link CURRENT_SCHEMA_VERSION} (ADR 0002).
+ *
+ * `api_key` used to live in the config file in plain text. It moves into
+ * `~/.orbitmap/credentials.json` under the `"default"` agent profile and is deleted from
+ * every config file it appears in — including the legacy `~/.orbitmap/config.json` when
+ * `ORBITMAP_CONFIG_HOME`/`XDG_CONFIG_HOME` moved the *written* file elsewhere, which would
+ * otherwise leave the plaintext secret sitting on disk forever under a message claiming it
+ * had been moved.
+ *
+ * The gate is the `schema_version` stamped by {@link mergeIntoFile}: once the file carries
+ * the current version, no later process looks at it again. The in-process flag only avoids
+ * repeating the work (and the warning) within a single run.
+ *
+ * Mutates `config` in place so the caller's already-parsed object reflects the migration.
+ * **On failure the legacy `api_key` is left in `config`** — `resolveAuth` falls back to it,
+ * so a machine where the write cannot happen (read-only `$HOME`, `credentials.json` owned
+ * by another user, a full disk) keeps working with the key it already has on disk instead
+ * of reporting "Missing API key" for a key that is right there.
+ */
+async function migrateGlobalConfig(config) {
+    if ((config.schema_version ?? 0) >= CURRENT_SCHEMA_VERSION)
+        return;
+    if (globalMigrationAttempted)
+        return;
+    globalMigrationAttempted = true;
+    const legacyKey = config.api_key;
+    const readPath = globalConfigReadPath();
+    const writePath = globalConfigWritePath();
+    try {
+        if (legacyKey)
+            await saveAgentProfile(LEGACY_AGENT_PROFILE, { api_key: legacyKey });
+        delete config.api_key;
+        await mergeIntoFile(writePath, config, readPath);
+        // The relocated file is now authoritative, but the legacy one still holds the secret.
+        if (legacyKey && readPath !== writePath)
+            await mergeIntoFile(readPath, config);
+        if (legacyKey) {
+            const also = readPath !== writePath ? ` and removed from ${readPath}` : '';
+            console.warn(`[orbitmap] Migrated the agent API key out of ${writePath}${also} into ` +
+                `${credentialsPath()} (profile "${LEGACY_AGENT_PROFILE}"). ` +
+                'See docs/adr/0002-project-scoped-config.md.');
+        }
+    }
+    catch (error) {
+        // Retry on the next run; the version stamp never landed, so the gate is still open.
+        globalMigrationAttempted = false;
+        if (!legacyKey)
+            return; // Nothing was at risk — only the version stamp failed to land.
+        // Loud, not silent: the key stays readable this run (restored here), but the user has
+        // to know their config file still holds a plaintext secret.
+        config.api_key = legacyKey;
+        console.warn(`[orbitmap] Could not migrate the agent API key out of ${readPath}: ` +
+            `${error instanceof Error ? error.message : String(error)}. The key is still in ` +
+            'plain text in that file and is being used from there for this run; fix the ' +
+            'permissions (or set ORBITMAP_CONFIG_HOME to a writable directory) and re-run.');
+    }
 }
-export async function resolveAuth() {
-    const config = await loadConfig();
-    const apiKey = process.env['ORBITMAP_API_KEY'] || config.api_key;
-    const apiUrl = process.env['ORBITMAP_API_URL'] ||
-        config.api_url ||
-        'https://orbitmap-main-x5n6qz.laravel.cloud/api/agent';
+/** Load `~/.orbitmap/config.json` (or the XDG/legacy equivalent). Runs the one-time
+ *  migration in {@link migrateGlobalConfig} as a side effect. */
+export async function loadConfig() {
+    const raw = await readRawConfigFile(globalConfigReadPath());
+    if (!raw)
+        return {};
+    const config = parseConfig(raw);
+    await migrateGlobalConfig(config);
+    return config;
+}
+/**
+ * Write the global `~/.orbitmap/config.json` (or its relocated equivalent).
+ *
+ * A **merge**, not a replace: keys already in the file that `config` does not set are kept
+ * (see {@link mergeIntoFile}). Never writes `api_key` — route secrets through
+ * `saveAgentProfile` in `oauth.ts` instead.
+ */
+export async function saveGlobalConfig(config) {
+    const file = globalConfigWritePath();
+    await mergeIntoFile(file, config, globalConfigReadPath());
+    return file;
+}
+// ── Project config ──────────────────────────────────────────────
+/**
+ * Write `<dir>/.orbitmap/config.json` (`dir` defaults to `process.cwd()`) and return its
+ * path. Committable — never write `api_key` or any other secret here.
+ *
+ * A **merge**, like {@link saveGlobalConfig}: this file is meant to be committed, so a
+ * teammate re-running `orbitmap init` in a checkout must not silently drop the `mode` (or
+ * any future field) the repository already agreed on — a loss that would then propagate to
+ * everyone through git.
+ */
+export async function saveProjectConfig(config, dir = process.cwd()) {
+    const file = join(resolve(dir), ORBITMAP_DIR, CONFIG_FILENAME);
+    await mergeIntoFile(file, config);
+    return file;
+}
+/**
+ * Resolve cloud-mode credentials. Per-field layering (ADR 0002), first match wins:
+ *
+ * - **API key**: `ORBITMAP_API_KEY` env → the resolved agent's profile in
+ *   `~/.orbitmap/credentials.json` → a legacy `api_key` still sitting in the global config
+ *   because {@link migrateGlobalConfig} could not write (see there).
+ * - **agent** (which profile to use, when the key isn't given directly by env):
+ *   `ORBITMAP_AGENT` env → nearest `.orbitmap/config.json` that sets `agent` → global
+ *   config `agent` → `"default"`.
+ * - **API URL**: `ORBITMAP_API_URL` env → {@link DEFAULT_API_URL}. There is deliberately no
+ *   config-file override any more — a single supported host means nothing should be able to
+ *   pin a stale one (see ADR 0002).
+ *
+ * **Area is deliberately not resolved here.** There is exactly one area ladder, `resolveArea`
+ * in `workspace-resolve.ts`; a second, shorter copy here used to disagree with it about the
+ * `link.json` rung. `createClient` applies the resolved area.
+ */
+export async function resolveAuth(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const config = options.config ?? (await loadConfig());
+    const apiUrl = process.env['ORBITMAP_API_URL'] || DEFAULT_API_URL;
+    let apiKey = process.env['ORBITMAP_API_KEY'];
+    if (!apiKey) {
+        const agent = process.env['ORBITMAP_AGENT'] ||
+            resolveProjectConfigField('agent', cwd)?.value ||
+            config.agent ||
+            LEGACY_AGENT_PROFILE;
+        apiKey = (await loadAgentProfile(agent))?.api_key;
+    }
+    // Last resort: an unmigrated global config (the migration write failed — it warned).
+    if (!apiKey)
+        apiKey = config.api_key;
     if (!apiKey) {
         throw new Error('Missing API key. Set ORBITMAP_API_KEY env var or run `orbitmap init`.');
     }
-    const projectId = process.env['ORBITMAP_PROJECT_ID'] || config.project_id;
-    return { apiKey, apiUrl, projectId };
-}
-export function resolveProjectId(explicit, envOrConfig) {
-    return explicit || process.env['ORBITMAP_PROJECT_ID'] || envOrConfig;
+    return { apiKey, apiUrl };
 }
 //# sourceMappingURL=config.js.map

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;AAQjC,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,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC;IAE1E,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,QAAiB,EACjB,WAAoB;IAEpB,OAAO,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC,IAAI,WAAW,CAAC;AACvE,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/doc-cache.d.ts

@@ -1,4 +1,4 @@
-import type { OrbitMapClient } from './api-client.js';
+import type { WorkspaceAdapter } from './adapters/types.js';
 export interface ManifestEntry {
     doc_id: string;
     version: number;
@@ -17,8 +17,28 @@ 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;
-export declare function downloadDocument(client: OrbitMapClient, idOrSlug: string): Promise<DownloadResult>;
+/**
+ * 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":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgC1C,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;AAC5C,MAAM,aAAa,GAAG,gBAAgB,CAAC;AACvC,MAAM,UAAU,GAAG,CAAC,CAAC;AAErB,MAAM,UAAU,WAAW;IACzB,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACpD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,EAAE,OAAO,CAAC,CAAa,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,QAAkB;IAC9C,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACpD,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,aAAa,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,MAAM,aAAa,GAAG,YAAY,CAAC;IACnC,MAAM,KAAK,GAAG,YAAY,CAAC;IAE3B,IAAI,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QACrD,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO;QACpC,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACrD,aAAa,CAAC,aAAa,EAAE,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,IAAI,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;SAAM,CAAC;QACN,aAAa,CAAC,aAAa,EAAE,GAAG,KAAK,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,MAAsB,EACtB,QAAgB;IAEhB,MAAM,QAAQ,GAAG,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAoB,CAAC;IACjF,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC1B,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEhC,gCAAgC;IAChC,IAAI,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,QAAQ,CAAC,aAAa,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YAClD,aAAa,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;QAChE,CAAC;IACH,CAAC;IAED,mBAAmB;IACnB,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,eAAe,EAAE,CAAC;IAElB,MAAM,QAAQ,GAAG,GAAG,IAAI,KAAK,CAAC;IAC9B,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE3C,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QACjC,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;SAAM,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACrC,6BAA6B;QAC7B,aAAa,CAAC,QAAQ,EAAE,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,qDAAqD,QAAQ,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAErC,QAAQ,CAAC,IAAI,CAAC,GAAG;QACf,MAAM,EAAE,GAAG,CAAC,EAAE;QACd,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,aAAa,EAAE,GAAG;QAClB,aAAa,EAAE,GAAG;QAClB,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,QAAQ;KACf,CAAC;IACF,aAAa,CAAC,QAAQ,CAAC,CAAC;IAExB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,iBAA2B;IACtD,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;IAChC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,OAAO,GAAG,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACjD,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAEhC,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,OAAO,EAAE,CAAC;QAC7D,IAAI,GAAG,GAAG,YAAY,IAAI,OAAO;YAAE,SAAS;QAE5C,2CAA2C;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,QAAQ,CAAC;gBAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,8BAA8B;QAChC,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"doc-cache.js","sourceRoot":"","sources":["../src/doc-cache.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -6,11 +6,28 @@ export interface ApiErrorBody {
         details?: Record<string, string[]>;
     };
 }
+/**
+ * Flat error shape used by billing/usage-limit rejections (402, 429):
+ * `error` is a string instead of an object.
+ */
+export interface FlatApiErrorBody {
+    error: string;
+    message?: string;
+    [key: string]: unknown;
+}
+/** No local workspace directory could be resolved (see workspace-resolve.ts). */
+export declare const WORKSPACE_NOT_FOUND = "WORKSPACE_NOT_FOUND";
+/** The command needs an area but none could be resolved (same code the API uses). */
+export declare const AREA_CONTEXT_REQUIRED = "AREA_CONTEXT_REQUIRED";
 export declare class OrbitMapAPIError extends Error {
     readonly code: string;
     readonly status: number;
-    readonly details?: Record<string, string[]>;
-    constructor(message: string, code: string, status: number, details?: Record<string, string[]>);
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, status: number, details?: Record<string, unknown>);
     static fromResponse(body: ApiErrorBody): OrbitMapAPIError;
+    static fromFlatResponse(body: FlatApiErrorBody, httpStatus: number): OrbitMapAPIError;
+    static workspaceNotFound(message?: string): OrbitMapAPIError;
+    static areaContextRequired(message?: string, details?: Record<string, unknown>): OrbitMapAPIError;
     static isApiErrorBody(body: unknown): body is ApiErrorBody;
+    static isFlatApiErrorBody(body: unknown): body is FlatApiErrorBody;
 }

package/dist/errors.js

@@ -1,3 +1,11 @@
+/** No local workspace directory could be resolved (see workspace-resolve.ts). */
+export const WORKSPACE_NOT_FOUND = 'WORKSPACE_NOT_FOUND';
+/** The command needs an area but none could be resolved (same code the API uses). */
+export const AREA_CONTEXT_REQUIRED = 'AREA_CONTEXT_REQUIRED';
+const FLAT_ERROR_CODES = {
+    402: 'PAYMENT_REQUIRED',
+    429: 'RATE_LIMITED',
+};
 export class OrbitMapAPIError extends Error {
     code;
     status;
@@ -13,14 +21,41 @@ export class OrbitMapAPIError extends Error {
         const { code, message, status, details } = body.error;
         return new OrbitMapAPIError(message, code, status, details);
     }
+    static fromFlatResponse(body, httpStatus) {
+        const message = body.message || body.error;
+        const code = FLAT_ERROR_CODES[httpStatus] ?? 'USAGE_LIMIT';
+        const details = {};
+        for (const [key, value] of Object.entries(body)) {
+            if (key !== 'error' && key !== 'message')
+                details[key] = value;
+        }
+        return new OrbitMapAPIError(message, code, httpStatus, Object.keys(details).length > 0 ? details : undefined);
+    }
+    static workspaceNotFound(message) {
+        return new OrbitMapAPIError(message ||
+            'No OrbitMap workspace found. Run `orbitmap init` to create one, or point at an ' +
+                'existing workspace with --workspace <path> or ORBITMAP_WORKSPACE.', WORKSPACE_NOT_FOUND, 404);
+    }
+    static areaContextRequired(message, details) {
+        return new OrbitMapAPIError(message ||
+            'Area context is required. Pass --area <slug>, set ORBITMAP_AREA, or set a default ' +
+                'area with `orbitmap init`.', AREA_CONTEXT_REQUIRED, 400, details);
+    }
     static isApiErrorBody(body) {
         return (typeof body === 'object' &&
             body !== null &&
             'error' in body &&
             typeof body.error === 'object' &&
+            body.error !== null &&
             typeof body.error.code === 'string' &&
             typeof body.error.message === 'string' &&
             typeof body.error.status === 'number');
     }
+    static isFlatApiErrorBody(body) {
+        return (typeof body === 'object' &&
+            body !== null &&
+            'error' in body &&
+            typeof body.error === 'string');
+    }
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AASA,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,CAAS;IACb,MAAM,CAAS;IACf,OAAO,CAA4B;IAE5C,YACE,OAAe,EACf,IAAY,EACZ,MAAc,EACd,OAAkC;QAElC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED,MAAM,CAAC,YAAY,CAAC,IAAkB;QACpC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;QACtD,OAAO,IAAI,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9D,CAAC;IAED,MAAM,CAAC,cAAc,CAAC,IAAa;QACjC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;YACxB,IAAI,KAAK,IAAI;YACb,OAAO,IAAI,IAAI;YACf,OAAQ,IAAqB,CAAC,KAAK,KAAK,QAAQ;YAChD,OAAQ,IAAqB,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;YACrD,OAAQ,IAAqB,CAAC,KAAK,CAAC,OAAO,KAAK,QAAQ;YACxD,OAAQ,IAAqB,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,CACxD,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.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>;