@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/directory-lens.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import { type SessionLens } from "./session-lens.js";
+/** A directory lens is the same shape as a session lens — same fields, different lifetime. */
+export type DirectoryLens = SessionLens;
+export interface FoundDirectoryLens {
+    lens: DirectoryLens;
+    /** Absolute path to the `.synap/lens.json` that supplied it — shown by `synap lens`. */
+    file: string;
+    /** The directory that owns it (the one containing `.synap/`). */
+    dir: string;
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export declare function lensSearchPath(startDir?: string): string[];
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export declare function findDirectoryLens(startDir?: string): FoundDirectoryLens | null;
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export declare function resolveDirectoryLensForPod(podUrl: string | undefined, startDir?: string): FoundDirectoryLens | null;
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export declare function effectiveDirectoryLens(lens: DirectoryLens): DirectoryLens;
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export declare function directoryLensWriteTarget(startDir?: string): string;
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export declare function writeDirectoryLens(patch: Partial<DirectoryLens>, startDir?: string): {
+    lens: DirectoryLens;
+    file: string;
+    dir: string;
+};
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export declare function clearDirectoryLensField(field?: keyof DirectoryLens, startDir?: string): string | null;

package/dist/lib/directory-lens.js

@@ -0,0 +1,187 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getClaudeSessionId, lensMatchesPod } from "./session-lens.js";
+import { writeSecretFile } from "./atomic-file.js";
+/** The directory name a lens lives in, and the file inside it. */
+const LENS_DIR_NAME = ".synap";
+const LENS_FILE_NAME = "lens.json";
+function lensFileIn(dir) {
+    return path.join(dir, LENS_DIR_NAME, LENS_FILE_NAME);
+}
+/** Is `dir` the home dir or inside it? Used to bound where a lens may be WRITTEN. */
+function isAtOrBelowHome(dir) {
+    const home = path.resolve(os.homedir());
+    const target = path.resolve(dir);
+    if (target === home)
+        return true;
+    return target.startsWith(home + path.sep);
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export function lensSearchPath(startDir = process.cwd()) {
+    const home = path.resolve(os.homedir());
+    const dirs = [];
+    let dir = path.resolve(startDir);
+    for (;;) {
+        dirs.push(dir);
+        if (dir === home)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return dirs;
+}
+/** Read + parse one candidate, or null when absent/corrupt. A malformed lens must not crash the CLI. */
+function readLensFile(dir) {
+    const file = lensFileIn(dir);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        return { lens: parsed, file, dir };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export function findDirectoryLens(startDir) {
+    for (const dir of lensSearchPath(startDir)) {
+        const found = readLensFile(dir);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export function resolveDirectoryLensForPod(podUrl, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    return lensMatchesPod(found.lens, podUrl) ? found : null;
+}
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export function effectiveDirectoryLens(lens) {
+    if (!getClaudeSessionId())
+        return lens;
+    const { focusSessionId: _conversationOwned, ...scope } = lens;
+    return scope;
+}
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export function directoryLensWriteTarget(startDir = process.cwd()) {
+    const found = findDirectoryLens(startDir);
+    if (found && isAtOrBelowHome(found.dir))
+        return found.dir;
+    return path.resolve(startDir);
+}
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export function writeDirectoryLens(patch, startDir) {
+    const dir = directoryLensWriteTarget(startDir);
+    const prev = readLensFile(dir)?.lens ?? {};
+    const next = { ...prev, ...patch, updatedAt: Date.now() };
+    const file = lensFileIn(dir);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    writeSecretFile(file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    return { lens: next, file, dir };
+}
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export function clearDirectoryLensField(field, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    if (!field) {
+        try {
+            fs.unlinkSync(found.file);
+        }
+        catch {
+            return null;
+        }
+        return found.file;
+    }
+    if (!(field in found.lens))
+        return null;
+    const next = { ...found.lens };
+    delete next[field];
+    next.updatedAt = Date.now();
+    try {
+        writeSecretFile(found.file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return found.file;
+}
+//# sourceMappingURL=directory-lens.js.map

package/dist/lib/directory-lens.js.map

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

package/dist/lib/exporter-coverage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What `--from-workspace` / `--from-project` do NOT carry out of a live pod.
+ * ==========================================================================
+ *
+ * `synap market publish --from-workspace <id>` serialises a LIVE workspace
+ * through the pod's `workspaceToPackageDefinition`
+ * (synap-backend/packages/api/src/services/workspace-to-package-definition.ts)
+ * and posts the result. `--from-project` walks the same serialiser for every
+ * workspace a project `uses`, then composes a suite — so the same drop-list
+ * applies to each constituent. That serialiser is a **lossy projection**: it
+ * emits 21 of `packageDefinitionSchema`'s keys and has no projection at all
+ * for the ones below. A workspace carrying them exports WITHOUT them — no
+ * error, no signal.
+ *
+ * Loops stay here deliberately: there is no durable loop row to reverse-
+ * serialise (`createLoopFromDefinition` dissolves into playbooks + triggers).
+ *
+ * The template guide used to assert, unqualified, that a
+ * `PackageDefinition` "round-trips". It does not, in this direction, and the
+ * consequence is the shape this repo keeps paying for: an author who built one
+ * of the things below publishes their workspace, ships a thinner-than-expected
+ * package, and gets a success message. Same class as `status ?? "installed"` —
+ * a claim of completeness nobody verified. (Cards authored in Card Studio USED
+ * to be one of these — `workspaceToPackageDefinition` now emits them into
+ * `cells[]`, so that loss is fixed; the list below is what remains.)
+ *
+ * ── WHY THIS LIST IS UNCONDITIONAL, NOT DETECTED ────────────────────────────
+ * The CLI never sees the workspace, only the projection's OUTPUT. "key absent
+ * because the workspace had none" and "key absent because the serialiser cannot
+ * emit it" are indistinguishable from here, and reporting a count would be
+ * inventing a fact. So this warns about the DOOR ("this door does not carry
+ * these"), which is true on every call, rather than about the payload.
+ *
+ * Keeping it honest across the repo boundary is
+ * `test/exporter-coverage-parity.test.ts`, which reads the exporter's own
+ * source and fails if a key listed here has gained an assignment (the list is
+ * stale and over-warns) or if a key it claims to emit has lost one.
+ */
+/** A `packageDefinitionSchema` key the workspace serialiser cannot emit. */
+export interface UnemittedKey {
+    /** The `PackageDefinition` key, verbatim. */
+    key: string;
+    /** What an author actually loses, in product words (Card, not cell). */
+    loses: string;
+}
+/**
+ * Keys with real user-authored content behind them that the serialiser drops.
+ *
+ * DELIBERATELY EXCLUDED, and why — these are absent from the export too, but
+ * warning about them would be noise rather than a loss:
+ *   • `icon` / `color` / `domain` / `workspaceType` — a live workspace has no
+ *     field to read them from (the exporter says so at L107-109). Honest
+ *     under-convergence, not a silent drop.
+ *   • `suggestedEntities` / `suggestedRelations` / `phases` / `composesFrom` —
+ *     authoring-time seed hints and composition metadata. A live workspace has
+ *     real entities, not "suggestions"; there is nothing to derive them from.
+ *   • `capability` / `sourcePackage` / `contentHash` — a non-workspace package
+ *     body and publish-time provenance. Not this door's business.
+ */
+export declare const EXPORTER_UNEMITTED_KEYS: readonly UnemittedKey[];
+/**
+ * The keys the serialiser DOES emit. Not consumed at runtime — it is the other
+ * half of the parity tripwire's assertion, so that "emits" and "does not emit"
+ * are pinned by the same read of the same source and cannot disagree.
+ */
+export declare const EXPORTER_EMITTED_KEYS: readonly string[];
+/**
+ * One human line per dropped key, for `--json`'s `warnings[]` and for the
+ * terminal hint list. Deliberately phrased as a property of the DOOR.
+ */
+export declare function exporterDropWarnings(): string[];

package/dist/lib/exporter-coverage.js

@@ -0,0 +1,97 @@
+/**
+ * What `--from-workspace` / `--from-project` do NOT carry out of a live pod.
+ * ==========================================================================
+ *
+ * `synap market publish --from-workspace <id>` serialises a LIVE workspace
+ * through the pod's `workspaceToPackageDefinition`
+ * (synap-backend/packages/api/src/services/workspace-to-package-definition.ts)
+ * and posts the result. `--from-project` walks the same serialiser for every
+ * workspace a project `uses`, then composes a suite — so the same drop-list
+ * applies to each constituent. That serialiser is a **lossy projection**: it
+ * emits 21 of `packageDefinitionSchema`'s keys and has no projection at all
+ * for the ones below. A workspace carrying them exports WITHOUT them — no
+ * error, no signal.
+ *
+ * Loops stay here deliberately: there is no durable loop row to reverse-
+ * serialise (`createLoopFromDefinition` dissolves into playbooks + triggers).
+ *
+ * The template guide used to assert, unqualified, that a
+ * `PackageDefinition` "round-trips". It does not, in this direction, and the
+ * consequence is the shape this repo keeps paying for: an author who built one
+ * of the things below publishes their workspace, ships a thinner-than-expected
+ * package, and gets a success message. Same class as `status ?? "installed"` —
+ * a claim of completeness nobody verified. (Cards authored in Card Studio USED
+ * to be one of these — `workspaceToPackageDefinition` now emits them into
+ * `cells[]`, so that loss is fixed; the list below is what remains.)
+ *
+ * ── WHY THIS LIST IS UNCONDITIONAL, NOT DETECTED ────────────────────────────
+ * The CLI never sees the workspace, only the projection's OUTPUT. "key absent
+ * because the workspace had none" and "key absent because the serialiser cannot
+ * emit it" are indistinguishable from here, and reporting a count would be
+ * inventing a fact. So this warns about the DOOR ("this door does not carry
+ * these"), which is true on every call, rather than about the payload.
+ *
+ * Keeping it honest across the repo boundary is
+ * `test/exporter-coverage-parity.test.ts`, which reads the exporter's own
+ * source and fails if a key listed here has gained an assignment (the list is
+ * stale and over-warns) or if a key it claims to emit has lost one.
+ */
+/**
+ * Keys with real user-authored content behind them that the serialiser drops.
+ *
+ * DELIBERATELY EXCLUDED, and why — these are absent from the export too, but
+ * warning about them would be noise rather than a loss:
+ *   • `icon` / `color` / `domain` / `workspaceType` — a live workspace has no
+ *     field to read them from (the exporter says so at L107-109). Honest
+ *     under-convergence, not a silent drop.
+ *   • `suggestedEntities` / `suggestedRelations` / `phases` / `composesFrom` —
+ *     authoring-time seed hints and composition metadata. A live workspace has
+ *     real entities, not "suggestions"; there is nothing to derive them from.
+ *   • `capability` / `sourcePackage` / `contentHash` — a non-workspace package
+ *     body and publish-time provenance. Not this door's business.
+ */
+export const EXPORTER_UNEMITTED_KEYS = [
+    { key: "commands", loses: "workspace commands" },
+    { key: "relationDefs", loses: "relation definitions" },
+    { key: "loops", loses: "loops" },
+    { key: "widgets", loses: "widget definitions" },
+    { key: "dependencies", loses: "declared package dependencies" },
+    { key: "defaultSources", loses: "declared workspace sources" },
+    { key: "sourceRoles", loses: "source roles" },
+];
+/**
+ * The keys the serialiser DOES emit. Not consumed at runtime — it is the other
+ * half of the parity tripwire's assertion, so that "emits" and "does not emit"
+ * are pinned by the same read of the same source and cannot disagree.
+ */
+export const EXPORTER_EMITTED_KEYS = [
+    "_meta",
+    "workspaceName",
+    "description",
+    "workspaceSubtype",
+    "workspaceVisibility",
+    "workspaceCapabilities",
+    "onboarding",
+    "profileEntityBentoTemplates",
+    "profiles",
+    "bentoLayout",
+    "bentoViewBlocks",
+    "bentoViewName",
+    "views",
+    "entityLinks",
+    "displayTemplates",
+    "automations",
+    "playbooks",
+    "capabilities",
+    "layoutConfig",
+    "actionPlacements",
+    "cells",
+];
+/**
+ * One human line per dropped key, for `--json`'s `warnings[]` and for the
+ * terminal hint list. Deliberately phrased as a property of the DOOR.
+ */
+export function exporterDropWarnings() {
+    return EXPORTER_UNEMITTED_KEYS.map((k) => `${k.key} — ${k.loses} (not exported: no projection)`);
+}
+//# sourceMappingURL=exporter-coverage.js.map

package/dist/lib/exporter-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporter-coverage.js","sourceRoot":"","sources":["../../src/lib/exporter-coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAUH;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA4B;IAC9D,EAAE,GAAG,EAAE,UAAU,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAChD,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,sBAAsB,EAAE;IACtD,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE;IAChC,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,oBAAoB,EAAE;IAC/C,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,+BAA+B,EAAE;IAC/D,EAAE,GAAG,EAAE,gBAAgB,EAAE,KAAK,EAAE,4BAA4B,EAAE;IAC9D,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,cAAc,EAAE;CAC9C,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,OAAO;IACP,eAAe;IACf,aAAa;IACb,kBAAkB;IAClB,qBAAqB;IACrB,uBAAuB;IACvB,YAAY;IACZ,6BAA6B;IAC7B,UAAU;IACV,aAAa;IACb,iBAAiB;IACjB,eAAe;IACf,OAAO;IACP,aAAa;IACb,kBAAkB;IAClB,aAAa;IACb,WAAW;IACX,cAAc;IACd,cAAc;IACd,kBAAkB;IAClB,OAAO;CACR,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,uBAAuB,CAAC,GAAG,CAChC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,gCAAgC,CAC7D,CAAC;AACJ,CAAC"}

package/dist/lib/goal-words.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A GOAL's words as `synap track` prints them — status, verdict, kind of
+ * work, uncertainty, criterion marks, what it waits on, who is on it, the
+ * end state's label.
+ *
+ * `@synap-core/types/vocabulary` is the one door for these words, but this
+ * package cannot import it (the CLI links only `@synap-core/hub-rest-client`
+ * and `@synap-core/workspace-templates`). So each table here is a COPY of the
+ * vocabulary's own, held EQUAL — keys and words — by
+ * `test/goal-words-parity.test.ts`, which reads the vocabulary's source in
+ * the sibling `synap-backend`. Delete this file for a plain import once the
+ * CLI depends on a published `@synap-core/types` carrying them.
+ */
+/** `TRACK_STATUS_LABELS` */
+export declare const TRACK_STATUS_LABELS: Readonly<Record<string, string>>;
+/** `TRACK_VERDICT_LABELS` */
+export declare const TRACK_VERDICT_LABELS: Readonly<Record<string, string>>;
+/** `TRACK_WORK_KIND_LABELS` */
+export declare const TRACK_WORK_KIND_LABELS: Readonly<Record<string, string>>;
+/** `TRACK_UNCERTAINTY_LABELS` */
+export declare const TRACK_UNCERTAINTY_LABELS: Readonly<Record<string, string>>;
+/** `GOAL_CRITERION_MARK_LABELS` */
+export declare const GOAL_CRITERION_MARK_LABELS: Readonly<Record<string, string>>;
+/** `WAITING_ON_REASON_LABELS` */
+export declare const WAITING_ON_REASON_LABELS: Readonly<Record<string, string>>;
+/** `TRACK_PARTICIPANT_ROLE_LABELS` (vocabulary/track-participant-words.ts) */
+export declare const TRACK_PARTICIPANT_ROLE_LABELS: Readonly<Record<string, string>>;
+/** `TRACK_COMMITMENT_STATE_LABELS` (vocabulary/track-participant-words.ts) */
+export declare const TRACK_COMMITMENT_STATE_LABELS: Readonly<Record<string, string>>;
+/** `GOAL_FIELD_LABELS` — the goal's stored fields as a person reads them. */
+export declare const GOAL_FIELD_LABELS: Readonly<Record<string, string>>;
+/**
+ * The vocabulary's fallback (`humanizeToken`, minus its cased-words list): a
+ * value no table names reads as words, never as the raw token.
+ */
+export declare function humanizeToken(token: string): string;
+/** A token through its table, else humanized — `""` for none. */
+export declare function goalWord(table: Readonly<Record<string, string>>, token: string | null | undefined): string;

package/dist/lib/goal-words.js

@@ -0,0 +1,112 @@
+/**
+ * A GOAL's words as `synap track` prints them — status, verdict, kind of
+ * work, uncertainty, criterion marks, what it waits on, who is on it, the
+ * end state's label.
+ *
+ * `@synap-core/types/vocabulary` is the one door for these words, but this
+ * package cannot import it (the CLI links only `@synap-core/hub-rest-client`
+ * and `@synap-core/workspace-templates`). So each table here is a COPY of the
+ * vocabulary's own, held EQUAL — keys and words — by
+ * `test/goal-words-parity.test.ts`, which reads the vocabulary's source in
+ * the sibling `synap-backend`. Delete this file for a plain import once the
+ * CLI depends on a published `@synap-core/types` carrying them.
+ */
+/** `TRACK_STATUS_LABELS` */
+export const TRACK_STATUS_LABELS = {
+    proposed: "Proposed",
+    agreed: "Agreed",
+    ready: "Ready",
+    active: "Active",
+    paused: "Paused",
+    completed: "Closed",
+    archived: "Dropped",
+};
+/** `TRACK_VERDICT_LABELS` */
+export const TRACK_VERDICT_LABELS = {
+    met: "Met",
+    partly_met: "Partly met",
+    not_met: "Not met",
+    retired: "Retired",
+    no_longer_needed: "No longer needed",
+    impossible: "Impossible",
+    replaced: "Replaced",
+    mistake: "Created by mistake",
+};
+/** `TRACK_WORK_KIND_LABELS` */
+export const TRACK_WORK_KIND_LABELS = {
+    project: "Project",
+    flow: "Flow",
+    operation: "Operation",
+    investigation: "Investigation",
+    incident: "Incident",
+    commission: "Commission",
+    pathway: "Pathway",
+};
+/** `TRACK_UNCERTAINTY_LABELS` */
+export const TRACK_UNCERTAINTY_LABELS = {
+    clear: "Clear",
+    complicated: "Complicated",
+    complex: "Complex",
+    chaotic: "Chaotic",
+    unknown: "Unknown",
+};
+/** `GOAL_CRITERION_MARK_LABELS` */
+export const GOAL_CRITERION_MARK_LABELS = {
+    met: "Met",
+    claimed: "Claimed",
+    under_way: "Under way",
+    not_met: "Not met",
+    not_started: "Not started",
+};
+/** `WAITING_ON_REASON_LABELS` */
+export const WAITING_ON_REASON_LABELS = {
+    input: "Input",
+    approval: "Approval",
+    access: "Access",
+    another_work: "Other work",
+    outside_world: "Outside world",
+};
+/** `TRACK_PARTICIPANT_ROLE_LABELS` (vocabulary/track-participant-words.ts) */
+export const TRACK_PARTICIPANT_ROLE_LABELS = {
+    owner: "Owner",
+    judge: "Judge",
+    delegate: "Delegate",
+    integrator: "Integrator",
+};
+/** `TRACK_COMMITMENT_STATE_LABELS` (vocabulary/track-participant-words.ts) */
+export const TRACK_COMMITMENT_STATE_LABELS = {
+    proposed: "Asked",
+    accepted: "Accepted",
+    countered: "Countered",
+    declined: "Declined",
+    reported_impossible: "Reported impossible",
+    done: "Done",
+};
+/** `GOAL_FIELD_LABELS` — the goal's stored fields as a person reads them. */
+export const GOAL_FIELD_LABELS = {
+    endState: "What done looks like",
+    criteria: "Done when",
+    workKind: "Kind of work",
+    uncertainty: "How well the way is known",
+    dropConditions: "Drop it if",
+};
+/**
+ * The vocabulary's fallback (`humanizeToken`, minus its cased-words list): a
+ * value no table names reads as words, never as the raw token.
+ */
+export function humanizeToken(token) {
+    const tail = token.includes(".") ? token.slice(token.lastIndexOf(".") + 1) : token;
+    const words = tail
+        .replace(/[_-]+/g, " ")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .trim()
+        .toLowerCase();
+    return words ? words.charAt(0).toUpperCase() + words.slice(1) : "";
+}
+/** A token through its table, else humanized — `""` for none. */
+export function goalWord(table, token) {
+    if (!token)
+        return "";
+    return Object.hasOwn(table, token) ? table[token] : humanizeToken(token);
+}
+//# sourceMappingURL=goal-words.js.map

package/dist/lib/goal-words.js.map

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