orbitmap 0.4.0-next.0 → 0.4.2

package/dist/paths.d.ts

@@ -0,0 +1,97 @@
+/** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). */
+export declare const ORBITMAP_DIR = ".orbitmap";
+/**
+ * Filename of *both* config files — `<project>/.orbitmap/config.json` (project-scoped,
+ * committable) and `~/.orbitmap/config.json` (machine-wide). Same name, different file:
+ * telling them apart is the job of {@link globalConfigPaths}, which the project walk-up
+ * below uses to skip the global one.
+ */
+export declare const CONFIG_FILENAME = "config.json";
+/** Filename of the machine-local secret store (`~/.orbitmap/credentials.json`). */
+export declare const CREDENTIALS_FILENAME = "credentials.json";
+/**
+ * Where the machine-wide OrbitMap files (`config.json`, `credentials.json`) live.
+ *
+ * `~/.orbitmap` was the only supported location before this module existed and remains the
+ * default. `ORBITMAP_CONFIG_HOME` (OrbitMap-specific) and `XDG_CONFIG_HOME` (the general
+ * Linux/BSD convention — see the XDG Base Directory spec) let a user relocate it; the CLI
+ * still reads the legacy `~/.orbitmap` location when the new one has no file yet, so
+ * existing installs keep working without a manual migration step.
+ */
+export interface OrbitMapHome {
+    /** Directory new files are written to. */
+    dir: string;
+    /** Pre-XDG default (`~/.orbitmap`), read as a fallback when `dir` differs from it. */
+    legacyDir: string;
+}
+/**
+ * The resolved OrbitMap home, memoised.
+ *
+ * Deliberately a *function*, not a module-level constant: the CLI's own tests (and any
+ * embedder) set `ORBITMAP_CONFIG_HOME`/`XDG_CONFIG_HOME` after this module has been
+ * imported, and a constant captured at import time would ignore them — and would give
+ * `config.ts` and `oauth.ts` two independent, silently diverging copies. The memo is keyed
+ * on the inputs, so a later env change is picked up while repeat calls stay free.
+ */
+export declare function resolveOrbitMapHome(): OrbitMapHome;
+/**
+ * Path to read `filename` from: the new `home.dir` location if the file exists there,
+ * otherwise the legacy `~/.orbitmap` location (which may or may not exist either — callers
+ * still need their own existence check). When `home.dir` and `home.legacyDir` are the same
+ * (the common case — neither `ORBITMAP_CONFIG_HOME` nor `XDG_CONFIG_HOME` set) this is a
+ * no-op and just returns the one path.
+ */
+export declare function resolveReadPath(home: OrbitMapHome, filename: string): string;
+/** Path to write `filename` to: always the new `home.dir` location. */
+export declare function resolveWritePath(home: OrbitMapHome, filename: string): string;
+/** Absolute path the global config is read from — the relocated one, or the legacy
+ *  `~/.orbitmap/config.json` when the relocated one does not exist yet. */
+export declare function globalConfigReadPath(): string;
+/** Absolute path the global config is written to — always the current home, which is not
+ *  necessarily where {@link globalConfigReadPath} read it from. */
+export declare function globalConfigWritePath(): string;
+/** Absolute path of the machine-local credential store, wherever the home now is. */
+export declare function credentialsPath(): string;
+/**
+ * Every path that is a *global* `config.json` for this machine — the current home and the
+ * legacy `~/.orbitmap` one, which is still read as a fallback. The project-config walk-up
+ * skips exactly these: same filename, different file, and pulling the global one in as if
+ * it were a project's own is the cross-project leak ADR 0002 exists to prevent.
+ */
+export declare function globalConfigPaths(): string[];
+/**
+ * Every existing `<dir>/.orbitmap/config.json` from `startDir` up to the user's home
+ * directory, **nearest first** — the same discovery behaviour as git looking for `.git`.
+ *
+ * This is the single implementation of the project-config walk-up; `project-config.ts`
+ * layers per-field resolution on top of it (ADR 0002 §2) and both `config.ts` and
+ * `workspace-resolve.ts` go through that, so a fix here applies to every ladder at once.
+ *
+ * Three invariants keep the global config out of the result:
+ *
+ * - **Any candidate equal to a {@link globalConfigPaths} entry is skipped.** That is the
+ *   real invariant — it holds regardless of where the global config actually lives, so it
+ *   also covers `ORBITMAP_CONFIG_HOME`/`XDG_CONFIG_HOME` relocating it somewhere in the
+ *   middle of the walk.
+ * - **Any candidate sitting next to a `credentials.json` is skipped** — see
+ *   {@link isOrbitMapHomeDir}, which catches a home the current `$HOME` no longer names.
+ * - **The walk stops at `$HOME`.** Nothing above a user's home is that user's project.
+ *   Compared canonically ({@link canonical}) rather than as raw strings, so a symlinked
+ *   `$HOME` (`/home/u` → `/data/home/u`) or a Windows case difference does not sail past it.
+ *   The original guard was an exact `===` on `resolve()`d strings and therefore failed on
+ *   both, silently handing the global config back as if it were a project's own.
+ */
+export declare function findProjectConfigFiles(startDir?: string): string[];
+/**
+ * Per-field walk-up: hand each project config file, nearest first, to `read` and return the
+ * first defined value together with the file it came from.
+ *
+ * "Nearest file that *sets this field* wins" — not "nearest file wins for everything".
+ * A monorepo package can set `agent` in its own `.orbitmap/config.json` and still inherit
+ * `mode`/`area` from the repository root, which is the per-field layering ADR 0002 §2
+ * promises (the `npm`/`git config` model).
+ */
+export declare function resolveProjectField<T>(startDir: string, read: (file: string) => T | undefined): {
+    value: T;
+    file: string;
+} | undefined;

package/dist/paths.js

@@ -0,0 +1,178 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+/** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). */
+export const ORBITMAP_DIR = '.orbitmap';
+/**
+ * Filename of *both* config files — `<project>/.orbitmap/config.json` (project-scoped,
+ * committable) and `~/.orbitmap/config.json` (machine-wide). Same name, different file:
+ * telling them apart is the job of {@link globalConfigPaths}, which the project walk-up
+ * below uses to skip the global one.
+ */
+export const CONFIG_FILENAME = 'config.json';
+/** Filename of the machine-local secret store (`~/.orbitmap/credentials.json`). */
+export const CREDENTIALS_FILENAME = 'credentials.json';
+let homeCache;
+/**
+ * The resolved OrbitMap home, memoised.
+ *
+ * Deliberately a *function*, not a module-level constant: the CLI's own tests (and any
+ * embedder) set `ORBITMAP_CONFIG_HOME`/`XDG_CONFIG_HOME` after this module has been
+ * imported, and a constant captured at import time would ignore them — and would give
+ * `config.ts` and `oauth.ts` two independent, silently diverging copies. The memo is keyed
+ * on the inputs, so a later env change is picked up while repeat calls stay free.
+ */
+export function resolveOrbitMapHome() {
+    const override = process.env['ORBITMAP_CONFIG_HOME'] ?? '';
+    const xdg = process.env['XDG_CONFIG_HOME'] ?? '';
+    const home = homedir();
+    const key = `${override}\u0000${xdg}\u0000${home}`;
+    if (homeCache?.key === key)
+        return homeCache.home;
+    const legacyDir = join(home, ORBITMAP_DIR);
+    const dir = override || (xdg ? join(xdg, 'orbitmap') : legacyDir);
+    const resolved = { dir, legacyDir };
+    homeCache = { key, home: resolved };
+    return resolved;
+}
+/**
+ * Path to read `filename` from: the new `home.dir` location if the file exists there,
+ * otherwise the legacy `~/.orbitmap` location (which may or may not exist either — callers
+ * still need their own existence check). When `home.dir` and `home.legacyDir` are the same
+ * (the common case — neither `ORBITMAP_CONFIG_HOME` nor `XDG_CONFIG_HOME` set) this is a
+ * no-op and just returns the one path.
+ */
+export function resolveReadPath(home, filename) {
+    const primary = join(home.dir, filename);
+    if (home.dir === home.legacyDir || existsSync(primary))
+        return primary;
+    const legacy = join(home.legacyDir, filename);
+    return existsSync(legacy) ? legacy : primary;
+}
+/** Path to write `filename` to: always the new `home.dir` location. */
+export function resolveWritePath(home, filename) {
+    return join(home.dir, filename);
+}
+/** Absolute path the global config is read from — the relocated one, or the legacy
+ *  `~/.orbitmap/config.json` when the relocated one does not exist yet. */
+export function globalConfigReadPath() {
+    return resolveReadPath(resolveOrbitMapHome(), CONFIG_FILENAME);
+}
+/** Absolute path the global config is written to — always the current home, which is not
+ *  necessarily where {@link globalConfigReadPath} read it from. */
+export function globalConfigWritePath() {
+    return resolveWritePath(resolveOrbitMapHome(), CONFIG_FILENAME);
+}
+/** Absolute path of the machine-local credential store, wherever the home now is. */
+export function credentialsPath() {
+    return resolveWritePath(resolveOrbitMapHome(), CREDENTIALS_FILENAME);
+}
+/**
+ * Every path that is a *global* `config.json` for this machine — the current home and the
+ * legacy `~/.orbitmap` one, which is still read as a fallback. The project-config walk-up
+ * skips exactly these: same filename, different file, and pulling the global one in as if
+ * it were a project's own is the cross-project leak ADR 0002 exists to prevent.
+ */
+export function globalConfigPaths() {
+    const home = resolveOrbitMapHome();
+    const paths = [join(home.dir, CONFIG_FILENAME)];
+    if (home.legacyDir !== home.dir)
+        paths.push(join(home.legacyDir, CONFIG_FILENAME));
+    return paths;
+}
+/**
+ * Canonical form of `path` for identity comparisons: symlinks resolved where the path
+ * exists, and lower-cased on Windows, whose filesystem is case-insensitive (`C:\Users\me`
+ * and `c:\users\me` are one directory). A plain `resolve()` string compare normalises
+ * neither, which is how the original `$HOME` walk-up guard silently failed.
+ */
+function canonical(path) {
+    let out = resolve(path);
+    try {
+        out = realpathSync.native(out);
+    }
+    catch {
+        // Does not exist (yet) — the lexical form is the best we can do, and is enough:
+        // a path that does not exist cannot be a config file we would have read anyway.
+    }
+    return process.platform === 'win32' ? out.toLowerCase() : out;
+}
+/**
+ * True when `orbitmapDir` is an OrbitMap *home* rather than a project's `.orbitmap/`.
+ *
+ * `credentials.json` is the machine-local secret store. The CLI only ever writes it into
+ * the resolved home ({@link resolveOrbitMapHome}) and never into a project directory, so
+ * finding one next to a `config.json` means that directory is a home — whatever the current
+ * `$HOME` happens to say.
+ *
+ * That distinction cannot be made from the path alone once `$HOME` is not what it was when
+ * the home was created: an overridden `HOME`/`USERPROFILE` (CI, `sudo`, a roaming profile,
+ * a test harness) leaves the real `~/.orbitmap/config.json` sitting on the walk-up path as
+ * an ordinary ancestor directory. Skipping it is always the safe direction — the worst case
+ * is that a rung falls through to the next one, never that one project's settings leak into
+ * another.
+ */
+function isOrbitMapHomeDir(orbitmapDir) {
+    return existsSync(join(orbitmapDir, CREDENTIALS_FILENAME));
+}
+/**
+ * Every existing `<dir>/.orbitmap/config.json` from `startDir` up to the user's home
+ * directory, **nearest first** — the same discovery behaviour as git looking for `.git`.
+ *
+ * This is the single implementation of the project-config walk-up; `project-config.ts`
+ * layers per-field resolution on top of it (ADR 0002 §2) and both `config.ts` and
+ * `workspace-resolve.ts` go through that, so a fix here applies to every ladder at once.
+ *
+ * Three invariants keep the global config out of the result:
+ *
+ * - **Any candidate equal to a {@link globalConfigPaths} entry is skipped.** That is the
+ *   real invariant — it holds regardless of where the global config actually lives, so it
+ *   also covers `ORBITMAP_CONFIG_HOME`/`XDG_CONFIG_HOME` relocating it somewhere in the
+ *   middle of the walk.
+ * - **Any candidate sitting next to a `credentials.json` is skipped** — see
+ *   {@link isOrbitMapHomeDir}, which catches a home the current `$HOME` no longer names.
+ * - **The walk stops at `$HOME`.** Nothing above a user's home is that user's project.
+ *   Compared canonically ({@link canonical}) rather than as raw strings, so a symlinked
+ *   `$HOME` (`/home/u` → `/data/home/u`) or a Windows case difference does not sail past it.
+ *   The original guard was an exact `===` on `resolve()`d strings and therefore failed on
+ *   both, silently handing the global config back as if it were a project's own.
+ */
+export function findProjectConfigFiles(startDir = process.cwd()) {
+    const found = [];
+    const globals = new Set(globalConfigPaths().map(canonical));
+    const homeStop = canonical(homedir());
+    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 (canonical(dir) === homeStop)
+            return found;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return found;
+        dir = parent;
+    }
+}
+/**
+ * Per-field walk-up: hand each project config file, nearest first, to `read` and return the
+ * first defined value together with the file it came from.
+ *
+ * "Nearest file that *sets this field* wins" — not "nearest file wins for everything".
+ * A monorepo package can set `agent` in its own `.orbitmap/config.json` and still inherit
+ * `mode`/`area` from the repository root, which is the per-field layering ADR 0002 §2
+ * promises (the `npm`/`git config` model).
+ */
+export function resolveProjectField(startDir, read) {
+    for (const file of findProjectConfigFiles(startDir)) {
+        const value = read(file);
+        if (value !== undefined)
+            return { value, file };
+    }
+    return undefined;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

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

package/dist/project-config.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The config file schema and the per-field project walk-up, in one place.
+ *
+ * This lives apart from `config.ts` (which owns the *global* file: loading it, migrating
+ * it, resolving credentials from it) so that both it and `workspace-resolve.ts` can use the
+ * one implementation without `workspace-resolve.ts` having to depend on the global-config
+ * machinery for it. The discovery underneath — walking up, skipping the global config,
+ * stopping at `$HOME` — lives in `paths.ts` and is shared with everything else.
+ *
+ * See `docs/adr/0002-project-scoped-config.md`.
+ */
+/** Storage backend for domain data. Absent in a config file means `'cloud'`. */
+export type OrbitMapMode = 'cloud' | 'local';
+/**
+ * Shape shared by both config files: `<project>/.orbitmap/config.json` and
+ * `~/.orbitmap/config.json`.
+ *
+ * Per ADR 0002 a config file holds **no secrets**. The agent's API key lives in
+ * `~/.orbitmap/credentials.json` (see `oauth.ts`), keyed by `agent` — the project says
+ * *which* agent to use, the machine holds *that agent's* credential. `api_key` below is a
+ * read-only fallback for configs written before this change; `loadConfig()` migrates it out
+ * on first read so it never appears in a config the CLI itself wrote.
+ *
+ * The interface lists the fields the CLI *understands*; it is not the full set of keys a
+ * file may hold. Both save functions merge into whatever is already on disk, so a key
+ * written by a newer (or older) version survives a write from this one — a read must never
+ * be able to destroy data (see `mergeIntoFile` in `config.ts`).
+ */
+export interface OrbitMapConfig {
+    /** On-disk format version of *this* file. `0`/absent = pre-ADR-0002. */
+    schema_version?: number;
+    /** `'cloud'` (default when absent) or `'local'`. */
+    mode?: OrbitMapMode;
+    /**
+     * Default local workspace directory. Global config only — a project's own workspace is
+     * found by the `.orbitmap/workspace.yml` / `link.json` walk-up, never by this field.
+     * **Must be absolute**: a relative value would resolve against the current directory and
+     * therefore mean a different workspace per project, which is the same cross-project leak
+     * ADR 0002 removes elsewhere. A relative value is ignored with a warning.
+     */
+    workspace_path?: string;
+    /** Name of the agent profile to use — looked up in `~/.orbitmap/credentials.json`. */
+    agent?: string;
+    /** Default area slug/id. */
+    area?: string;
+    /** @deprecated Legacy secret, read once for migration then dropped. Never written. */
+    api_key?: string;
+}
+/**
+ * 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
+ * represented here but are never lost on write (see `mergeIntoFile` in `config.ts`).
+ */
+export declare function parseConfig(raw: unknown): OrbitMapConfig;
+/** Read and validate one project `.orbitmap/config.json`; `undefined` when it is missing or
+ *  malformed — a broken file is treated as absent rather than throwing mid-ladder. */
+export declare function readProjectConfigFile(file: string): OrbitMapConfig | undefined;
+/** One field's value together with the project config file that supplied it. */
+export interface ResolvedProjectField<T> {
+    value: T;
+    /** Absolute path of the `.orbitmap/config.json` the value came from. */
+    file: string;
+}
+/**
+ * Resolve one field by walking up from `startDir`, **per field** (ADR 0002 §2): the nearest
+ * `.orbitmap/config.json` that actually *sets* `field` wins, not merely the nearest file.
+ *
+ * A monorepo package that pins only its own `agent` still inherits `mode` and `area` from
+ * the repository root — with "nearest file wins as a unit" the root's settings would vanish
+ * the moment a package added a config of its own.
+ *
+ * Sync (like `findLinkFile` in `workspace-resolve.ts`) so the synchronous resolution ladders
+ * can use it without threading promises through every rung.
+ */
+export declare function resolveProjectConfigField<K extends keyof OrbitMapConfig>(field: K, startDir?: string): ResolvedProjectField<NonNullable<OrbitMapConfig[K]>> | undefined;

package/dist/project-config.js

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { resolveProjectField } from './paths.js';
+/**
+ * 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
+ * represented here but are never lost on write (see `mergeIntoFile` in `config.ts`).
+ */
+export function parseConfig(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return {};
+    const r = raw;
+    const config = {};
+    if (typeof r['schema_version'] === 'number')
+        config.schema_version = r['schema_version'];
+    if (r['mode'] === 'cloud' || r['mode'] === 'local')
+        config.mode = r['mode'];
+    if (typeof r['workspace_path'] === 'string' && r['workspace_path']) {
+        config.workspace_path = r['workspace_path'];
+    }
+    if (typeof r['agent'] === 'string' && r['agent'])
+        config.agent = r['agent'];
+    if (typeof r['area'] === 'string' && r['area'])
+        config.area = r['area'];
+    if (typeof r['api_key'] === 'string' && r['api_key'])
+        config.api_key = r['api_key'];
+    return config;
+}
+/** Read and validate one project `.orbitmap/config.json`; `undefined` when it is missing or
+ *  malformed — a broken file is treated as absent rather than throwing mid-ladder. */
+export function readProjectConfigFile(file) {
+    try {
+        return parseConfig(JSON.parse(readFileSync(file, 'utf-8')));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one field by walking up from `startDir`, **per field** (ADR 0002 §2): the nearest
+ * `.orbitmap/config.json` that actually *sets* `field` wins, not merely the nearest file.
+ *
+ * A monorepo package that pins only its own `agent` still inherits `mode` and `area` from
+ * the repository root — with "nearest file wins as a unit" the root's settings would vanish
+ * the moment a package added a config of its own.
+ *
+ * Sync (like `findLinkFile` in `workspace-resolve.ts`) so the synchronous resolution ladders
+ * can use it without threading promises through every rung.
+ */
+export function resolveProjectConfigField(field, startDir = process.cwd()) {
+    const hit = resolveProjectField(startDir, (file) => readProjectConfigFile(file)?.[field]);
+    return hit
+        ? { value: hit.value, file: hit.file }
+        : undefined;
+}
+//# sourceMappingURL=project-config.js.map

package/dist/project-config.js.map

@@ -0,0 +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"}

package/dist/workspace-resolve.d.ts

@@ -1,7 +1,10 @@
 import { type OrbitMapConfig, type OrbitMapMode } from './config.js';
+import { ORBITMAP_DIR } from './paths.js';
 export type { OrbitMapMode };
-/** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). */
-export declare const ORBITMAP_DIR = ".orbitmap";
+/** Name of the per-project OrbitMap directory (`<project>/.orbitmap`). Defined in
+ *  `paths.ts` (which owns the project-config walk-up) and re-exported here, where most
+ *  callers already look for it. */
+export { ORBITMAP_DIR };
 /** Project-local pointer at a workspace living elsewhere on disk. */
 export declare const LINK_FILE = "link.json";
 /** Marker file that identifies a directory as a local workspace. */
@@ -48,18 +51,32 @@ export interface ResolveOptions {
     link?: FoundWorkspaceLink | undefined;
 }
 /**
- * Mode resolution (§3.3) — **per project first, global config only as a fallback**,
- * first match wins:
+ * Mode resolution (ADR 0002, extending spec §3.3) — **per project first, global config
+ * only as a fallback**, first match wins:
  *
  * 1. `--workspace <path>` flag → local (explicit override, no further checks)
  * 2. `ORBITMAP_MODE=local|cloud` → that mode, for this invocation
- * 3. local auto-detect: nearest `.orbitmap/link.json` or `.orbitmap/workspace.yml`,
+ * 3. nearest `.orbitmap/config.json` **that sets `mode`** → that value **[ADR 0002]**
+ * 4. local auto-detect: nearest `.orbitmap/link.json` or `.orbitmap/workspace.yml`,
  *    walking up from cwd to the filesystem root (as git looks for `.git`) → local
- * 4. global config `mode` (absent or unknown ⇒ `'cloud'`)
+ * 5. global config `mode` (absent or unknown ⇒ `'cloud'`)
  *
- * Rung 3 is what keeps projects independent: a directory that ran `orbitmap init` → local
- * is local from then on, and a directory that never did keeps resolving through its own
- * config — one project's choice can never flip another's.
+ * Rung 3 is resolved **per field** (`resolveProjectConfigField`), not "nearest file wins":
+ * a `packages/api/.orbitmap/config.json` that only pins an `agent` does not shadow the
+ * repository root's `mode`. See ADR 0002 §2.
+ *
+ * Rung 3 exists because the whole per-project scoping mechanism (link.json,
+ * workspace.yml-based auto-detect) was originally built only for *local* mode — a cloud
+ * project had no file of its own to declare itself cloud in, so it depended entirely on
+ * rung 5 never being flipped by another project. `.orbitmap/config.json` gives cloud
+ * projects that same voice, and it outranks rung 4 on purpose: a project that explicitly
+ * declares `mode: "cloud"` must not be dragged back into local mode by a leftover
+ * `link.json`/`workspace.yml` in the same directory.
+ *
+ * Rung 4 is what keeps *un-declared* projects independent: a directory that ran
+ * `orbitmap init` → local is local from then on via its own marker file, and a directory
+ * that never did keeps resolving through its own config — one project's choice can never
+ * flip another's.
  */
 export declare function resolveMode(options?: ResolveOptions): OrbitMapMode;
 /**
@@ -68,36 +85,51 @@ export declare function resolveMode(options?: ResolveOptions): OrbitMapMode;
  * 2. `ORBITMAP_WORKSPACE` env var
  * 3. nearest `.orbitmap/link.json` (walking up from cwd) → its `workspace` field
  * 4. nearest `.orbitmap/workspace.yml` (walking up from cwd) → that `.orbitmap`
- * 5. global config `workspace_path`
- * 6. otherwise: `OrbitMapAPIError` with code `WORKSPACE_NOT_FOUND`
+ * 5. the `.orbitmap/` directory of the nearest project config that sets `mode: "local"`,
+ *    when that directory is itself a workspace **[ADR 0002]**
+ * 6. global config `workspace_path` — **must be absolute** (a relative value is ignored
+ *    with a warning; see {@link OrbitMapConfig.workspace_path})
+ * 7. otherwise: `OrbitMapAPIError` with code `WORKSPACE_NOT_FOUND`
  *
- * The returned path is absolute; its existence is not verified (except for rung 4,
- * which is defined by the marker file).
+ * Rung 5 is what makes a committed `{"mode": "local"}` usable on its own: without it, a
+ * project config that declares local mode has nowhere to point and every command fails with
+ * `WORKSPACE_NOT_FOUND`. It usually resolves to the same directory as rung 4 — the point is
+ * that it does not *depend* on the auto-detect walk finding the marker first, and that it
+ * anchors on the config file that made this project local rather than on the current
+ * directory.
+ *
+ * The returned path is absolute; its existence is not verified (except for rungs 4 and 5,
+ * which are defined by the marker file).
  */
 export declare function resolveWorkspacePath(options?: ResolveOptions): string;
 /**
  * Which rung of the area ladder produced a slug.
  *
- * `flag`/`env`/`link` are **explicit**: the user (or the project's own `link.json`) named
- * that area, so a slug that does not exist must fail loudly. `config` is the machine-wide
- * default — the weakest rung, and the only one a local workspace is allowed to override
- * or ignore (see `createLocalContext`).
+ * `flag`/`env`/`link`/`project-config` are **explicit**: the user, the project's own
+ * `link.json`, or the project's own `.orbitmap/config.json` named that area, so a slug that
+ * does not exist must fail loudly. `config` is the machine-wide default (the deprecated
+ * global `~/.orbitmap/config.json` `area` — ADR 0002) — the weakest rung, and the only one
+ * a local workspace is allowed to override or ignore (see `createLocalContext`).
  */
-export type AreaSource = 'flag' | 'env' | 'link' | 'config';
+export type AreaSource = 'flag' | 'env' | 'link' | 'project-config' | 'config';
 /** An area slug together with the rung it came from. */
 export interface ResolvedAreaSlug {
     area?: string;
     source?: AreaSource;
 }
 /**
- * Area resolution (§3.3), explicit sources only:
- * `--area` → `ORBITMAP_AREA` → `link.json.area` → global config `area`.
+ * Area resolution (ADR 0002, extending spec §3.3), explicit sources only:
+ * `--area` → `ORBITMAP_AREA` → `link.json.area` → nearest `.orbitmap/config.json`
+ * **that sets `area`** **[ADR 0002]** → global config `area` (deprecated).
+ *
+ * The project-config rung is per-field (`resolveProjectConfigField`): a nested config that
+ * sets only `agent` does not hide an `area` pinned by the repository root.
  *
  * The two remaining rungs — the workspace's own `workspace.yml` `default_area` (which
- * sits *between* `link.json` and the global config) and "workspace has exactly one area →
- * auto-select it" — require reading the workspace tree and therefore live in the local
- * adapter (`createLocalContext`); this function stays synchronous and file-store-free so
- * that cloud mode never touches a workspace file. The `source` lets the adapter tell an
+ * sits *between* the project config and the global config) and "workspace has exactly one
+ * area → auto-select it" — require reading the workspace tree and therefore live in the
+ * local adapter (`createLocalContext`); this function stays synchronous and file-store-free
+ * so that cloud mode never touches a workspace file. The `source` lets the adapter tell an
  * explicit request apart from the machine-wide default.
  */
 export declare function resolveArea(options?: ResolveOptions): ResolvedAreaSlug;