@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/repo/repo.js

@@ -0,0 +1,308 @@
+/**
+ * Read model of the docs repo — enumeration, and only by the filesystem.
+ *
+ * Files are the source of truth, so `services/` IS the list of services and
+ * there is no manifest that can disagree with it. The shapes this hands back
+ * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is
+ * a repo to walk at all in `state.ts`.
+ */
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { contentStamp, listField, movedUnderVouch, readFrontmatter, stringField, } from "../document/frontmatter.js";
+import { featureDirOf } from "../kernel/ids/dirs.js";
+import { rawServiceId, serviceIdProblem } from "../kernel/ids/service.js";
+import { readVouchScope } from "../provenance/sample/scope.js";
+import { compareIds, featureIdFromDirName } from "./entries.js";
+import { ARCHIVE_DIR, featurePaths, featuresDir, fleetAdrsDir, isServiceArtifactName, servicePathsAt, SPEC_AXES, } from "./paths.js";
+import { requireDocsRepo } from "./state.js";
+import { countMarkdown, entryIs } from "./tree/fs.js";
+import { walkServicesTree } from "./tree/walk.js";
+/* ------------------------------------------------------------------ */
+/* Enumeration                                                         */
+/* ------------------------------------------------------------------ */
+/**
+ * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).
+ * A missing `dir` is an empty list — the swallow is deliberate but narrow: it
+ * only ever runs INSIDE a docs repo that `requireDocsRepo` has already
+ * confirmed, where an absent `features/` or `specs/` means "none yet" and
+ * nothing else.
+ */
+async function subdirs(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+        .filter((e) => !e.name.startsWith(".") && entryIs(dir, e, "dir"))
+        .map((e) => e.name)
+        .sort(compareIds);
+}
+/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */
+export async function featureSpecServices(featureDir, context) {
+    if (context !== undefined)
+        return context.featureSpecServices(featureDir);
+    return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);
+}
+/**
+ * The classified `services/` tree — services at any depth, the subsystems
+ * grouping them, and the walk's own findings (`subsystem.*`). The walk itself
+ * lives in `./tree/walk.ts` and never imports back into this package; this
+ * function is where its two injected dependencies are built — the docs-repo
+ * precondition and the artifact-name table `paths.ts` owns.
+ */
+export async function listFleetTree(docsDir, context) {
+    if (context !== undefined)
+        return context.fleetTree(docsDir);
+    requireDocsRepo(docsDir, ["ok"]);
+    return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });
+}
+/** Every service in the docs repo, at any depth of the tree, ordered by id. */
+export async function listServices(docsDir, context) {
+    if (context !== undefined)
+        return context.listServices(docsDir);
+    return serviceEntries(await listFleetTree(docsDir));
+}
+/**
+ * The full entries for a walked tree — frontmatter, artifact presence, ADR
+ * count. Split from `listServices` so `FleetContext` can derive its services
+ * memo from its tree memo: one walk per invocation answers both questions.
+ * Ordering is `compareIds` over the id wherever the service sits — placement
+ * is never part of any identity, and `--json` consumers diff this order — with
+ * the directory as the tiebreak so a duplicated id (its own error finding)
+ * still lists deterministically.
+ */
+/**
+ * The second spec axis's header, or an empty one when nobody could read it.
+ *
+ * `readFrontmatter` folds a decode failure into a flag but still THROWS when
+ * the path exists and cannot be read as a file at all — a directory named
+ * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is
+ * the fleet ENUMERATION, where one service's bad byte must cost one subject
+ * and not the listing of the other 119, so the throw stops here.
+ *
+ * The distinction between "no scope" and "nobody could look" is not lost by
+ * swallowing it: a path that exists and cannot be read is `service.unreadable`
+ * — an ERROR that fails `loam validate` and `loam gate` — which is a louder
+ * signal than any row of a listing, and it names the file this cannot.
+ */
+async function archHeader(path) {
+    try {
+        return await readFrontmatter(path);
+    }
+    catch {
+        return { present: false, malformed: false, data: {}, body: "" };
+    }
+}
+/**
+ * The spec files whose body moved under their vouch — `content.stale`'s
+ * question, asked through the one predicate `loam validate` grades with
+ * (`movedUnderVouch`) so the fleet listing and the finding cannot disagree
+ * about one file. Only a header that carries a stamp (`contentStamp`) costs the
+ * second read: the frontmatter read already answered whether there is anything
+ * to compare, and on a fleet mid-adoption most headers do not. The body is
+ * read exactly as the finding reads it, as UTF-8 text, because the stamp is
+ * byte-exact.
+ */
+async function filesMovedUnderVouch(axes) {
+    const moved = await Promise.all(axes.map(async ({ file, path, header }) => contentStamp(header) !== undefined && movedUnderVouch(header, await readFile(path, "utf8")) ? [file] : []));
+    return moved.flat();
+}
+/**
+ * `ServiceEntry.adoption`, read off one living spec.md's frontmatter — the one
+ * spelling of the marker's test, for the enumeration below and for the adopt
+ * brief, which must not call a partial adoption finished. Any value but
+ * `partial` reads as absent (SCHEMA.md).
+ */
+export function adoptionOf(fm) {
+    return stringField(fm, "adoption") === "partial" ? "partial" : null;
+}
+/** `adoptionOf` for a spec.md by path; an absent file is no marker. */
+export async function specAdoption(specPath) {
+    return adoptionOf(await readFrontmatter(specPath));
+}
+export async function serviceEntries(tree) {
+    const entries = await Promise.all(tree.services.map(async (svc) => {
+        const p = servicePathsAt(svc.dir);
+        // Both spec axes, because a sample is per FILE: one `--sample 3` run can
+        // read a short spec.md in full and stamp a scope on a long arch.spec.md
+        // beside it, and a fleet row that reported only spec.md's header would
+        // print that service as fully vouched while `loam validate` reported it
+        // sampled. `readFrontmatter` answers "absent" for a file that is not
+        // there, so a service without the second axis pays one existsSync.
+        const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);
+        const headers = { spec: fm, archSpec: archFm };
+        const idProblem = serviceIdProblem(svc.id, "directory name");
+        return {
+            id: svc.id,
+            dir: svc.dir,
+            subsystem: svc.subsystem,
+            ...(idProblem === null ? {} : { idProblem }),
+            has: {
+                model: existsSync(p.model),
+                spec: existsSync(p.spec),
+                openapi: existsSync(p.openapi),
+                asyncapi: existsSync(p.asyncapi),
+                runbook: existsSync(p.runbook),
+                health: existsSync(p.health),
+            },
+            adrs: await countMarkdown(p.adrsDir),
+            status: stringField(fm, "status") ?? null,
+            adoption: adoptionOf(fm),
+            sources: {
+                declared: listField(fm, "sources").length > 0,
+                stamped: stringField(fm, "sources_digest") !== undefined,
+            },
+            // Either axis makes the SERVICE sampled, and presence is the test, not
+            // decodability: an unreadable scope is still a stamped partial read
+            // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet
+            // listing is the last place a mangled field should be able to buy
+            // itself a full-trust row.
+            vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== "none") ? "sampled" : null,
+            // Both axes again, for the scope's reason: a stamp is per FILE, and an
+            // arch.spec.md edited under its vouch is a service part of whose
+            // documentation nobody has re-read.
+            contentStale: await filesMovedUnderVouch(SPEC_AXES.map((axis) => ({ file: axis.file, path: p[axis.key], header: headers[axis.key] }))),
+        };
+    }));
+    return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));
+}
+/**
+ * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the
+ * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude
+ * down. One shape for one question: a second spelling of "count the decisions"
+ * is how `list` and `show` once reported different ADR counts for one service.
+ *
+ * A count and never a finding. The directory is optional, an absent one is 0,
+ * and nothing in loam grades either — see `fleetAdrsDir` for why that is the
+ * whole design rather than an unfinished half of it. No `FleetContext` overload:
+ * one caller asks this once per invocation, and a memo whose key is the docsDir
+ * would be a cache nobody reads twice.
+ */
+export async function fleetAdrCount(docsDir) {
+    return countMarkdown(fleetAdrsDir(docsDir));
+}
+/**
+ * What a feature is CALLED, for a person: intent.md's `title:`, else its first
+ * `# ` heading with the feature id peeled off the front, else null.
+ *
+ * Every row that names a feature used to print the id alone, and an id is a
+ * key, not a name — a newcomer looking at `ready  FEAT-101` could not tell
+ * which change it was without opening the directory. Read on demand rather
+ * than carried on `FeatureEntry`, because the enumeration runs under every
+ * command and only the views a person reads need the words. A missing or
+ * unreadable intent.md is simply no title: the row still prints its id, and
+ * whether intent.md is owed is `status`'s question, not this one's.
+ */
+export async function featureTitle(feature) {
+    let fm;
+    try {
+        fm = await readFrontmatter(featurePaths(feature.dir).intent);
+    }
+    catch {
+        // A directory in intent.md's place, a permission: unreadable is no title.
+        // `readFrontmatter` folds only the encoding failure into a flag, and before
+        // this read the views that print a title never opened intent.md at all —
+        // so letting the error escape would hand `loam status` and `loam list`
+        // whole to `repository-unavailable` over a label. Whether intent.md is
+        // fine is the intent row's and `validate`'s question.
+        return null;
+    }
+    const declared = stringField(fm, "title")?.trim();
+    if (declared !== undefined && declared !== "")
+        return declared;
+    const heading = fm.body.split(/\r?\n/).find((l) => l.startsWith("# "));
+    if (heading === undefined)
+        return null;
+    const words = heading.slice(2).trim();
+    const bare = words.startsWith(feature.id) ? words.slice(feature.id.length).replace(/^[\s:—–-]+/, "") : words;
+    return bare === "" ? null : bare;
+}
+async function readFeature(dir, dirName, archived) {
+    const p = featurePaths(dir);
+    return {
+        id: featureIdFromDirName(dirName),
+        dirName,
+        dir,
+        archived,
+        services: (await subdirs(p.specsDir)).map(rawServiceId),
+        has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },
+    };
+}
+/**
+ * Features in the docs repo, ordered by id (active and archived interleaved when
+ * both are asked for). `features/archive/` is the archive, never a feature.
+ */
+export async function listFeatures(docsDir, opts = {}, context) {
+    if (context !== undefined)
+        return context.listFeatures(docsDir, opts);
+    // "no-services" is tolerated here on purpose: a docs repo whose services/ is
+    // gone is broken, but it is `listServices` (and `loam doctor`) that says so.
+    // Refusing here too would turn one diagnosis into two contradictory ones.
+    requireDocsRepo(docsDir, ["ok", "no-services"]);
+    const root = featuresDir(docsDir);
+    const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);
+    // Branded at the join: the name came off this readdir, onto the features
+    // root it was listed under — the provenance `FeatureDir` records.
+    const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));
+    if (opts.includeArchived) {
+        const archiveRoot = join(root, ARCHIVE_DIR);
+        const archived = await subdirs(archiveRoot);
+        out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));
+    }
+    return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));
+}
+/**
+ * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory
+ * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical
+ * spelling, and it is the only name a caller may use from here on: tag filters,
+ * coherence, and the cross-feature self-exclusion scans all compare against
+ * `feature.id`, never against the raw argument.
+ *
+ * Matching is EXACT, on one of two spellings: the directory name as it is on
+ * disk, or the canonical id derived from it. It used to also match any dirName
+ * starting with `arg + "-"`, which made the argument a prefix query in
+ * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived
+ * whichever sorted first, and `loam delta billing` reached into
+ * `billing-7-rewrite`. A destructive command must never pick a target the
+ * caller did not name, so a prefix now resolves to nothing at all.
+ *
+ * An exact directory name still wins over the id spelling (`FEAT-5` the
+ * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under "include"
+ * an active feature wins over an archived one. Ties among equally-exact
+ * candidates go to the first by name — deterministic, unlike the raw readdir
+ * order this replaces; `featureCandidates` returns every one of them, for a
+ * caller that must see the tie (`loam status` names the colliding directories).
+ */
+export async function resolveFeature(docsDir, arg, archived, context) {
+    return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;
+}
+/**
+ * Every feature the argument names exactly, best first. Split out of
+ * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can
+ * see the tie instead of inheriting the winner.
+ */
+export async function featureCandidates(docsDir, arg, archived, context) {
+    const all = await listFeatures(docsDir, { includeArchived: archived !== "exclude" }, context);
+    return all
+        .filter((f) => archived === "include" || f.archived === (archived === "only"))
+        .filter((f) => f.dirName === arg || f.id === arg)
+        .sort((a, b) => Number(b.dirName === arg) - Number(a.dirName === arg) ||
+        Number(a.archived) - Number(b.archived) ||
+        compareIds(a.dirName, b.dirName));
+}
+/**
+ * The message for an exclude-mode miss. When the feature exists under
+ * `features/archive/`, "no feature" is a lie the caller would have to debug —
+ * the honest answer is "already archived", plus how to look at it. The `--json`
+ * code stays `unknown-target` either way: the target is unknown to the command
+ * that asked, and the prose carries the diagnosis.
+ */
+export async function missingFeatureMessage(docsDir, arg, context) {
+    const shipped = await resolveFeature(docsDir, arg, "only", context);
+    if (shipped !== null) {
+        return (`Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +
+            `\`loam show ${shipped.id}\` reads it, \`loam unarchive ${shipped.id}\` re-opens it.`);
+    }
+    return `No feature '${arg}' under ${featuresDir(docsDir)}.`;
+}
+//# sourceMappingURL=repo.js.map

package/dist/core/repo/repo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"repo.js","sourceRoot":"","sources":["../../../src/core/repo/repo.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Read model of the docs repo — enumeration, and only by the filesystem.\n *\n * Files are the source of truth, so `services/` IS the list of services and\n * there is no manifest that can disagree with it. The shapes this hands back\n * live in `entries.ts`, the layout it walks in `paths.ts`, and whether there is\n * a repo to walk at all in `state.ts`.\n */\nimport { existsSync } from \"node:fs\";\nimport { readdir, readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport {\n  contentStamp,\n  listField,\n  movedUnderVouch,\n  readFrontmatter,\n  stringField,\n  type Frontmatter,\n} from \"../document/frontmatter.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureDirOf, type DocsDir, type FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { rawServiceId, serviceIdProblem, type RawServiceId } from \"../kernel/ids/service.js\";\nimport { readVouchScope } from \"../provenance/sample/scope.js\";\nimport { compareIds, featureIdFromDirName, type FeatureEntry, type ServiceEntry } from \"./entries.js\";\nimport {\n  ARCHIVE_DIR,\n  featurePaths,\n  featuresDir,\n  fleetAdrsDir,\n  isServiceArtifactName,\n  servicePathsAt,\n  SPEC_AXES,\n} from \"./paths.js\";\nimport { requireDocsRepo } from \"./state.js\";\nimport { countMarkdown, entryIs } from \"./tree/fs.js\";\nimport { walkServicesTree, type FleetTree } from \"./tree/walk.js\";\n\n/* ------------------------------------------------------------------ */\n/* Enumeration                                                         */\n/* ------------------------------------------------------------------ */\n\n/**\n * Sorted names of the real subdirectories of `dir` (dot-dirs and files skipped).\n * A missing `dir` is an empty list — the swallow is deliberate but narrow: it\n * only ever runs INSIDE a docs repo that `requireDocsRepo` has already\n * confirmed, where an absent `features/` or `specs/` means \"none yet\" and\n * nothing else.\n */\nasync function subdirs(dir: string): Promise<string[]> {\n  if (!existsSync(dir)) return [];\n  const entries = await readdir(dir, { withFileTypes: true });\n  return entries\n    .filter((e) => !e.name.startsWith(\".\") && entryIs(dir, e, \"dir\"))\n    .map((e) => e.name)\n    .sort(compareIds);\n}\n\n/** Services a feature carries a delta for, ordered — the subdirs of its specs/. */\nexport async function featureSpecServices(\n  featureDir: FeatureDir,\n  context?: FleetContext,\n): Promise<RawServiceId[]> {\n  if (context !== undefined) return context.featureSpecServices(featureDir);\n  return (await subdirs(featurePaths(featureDir).specsDir)).map(rawServiceId);\n}\n\n/**\n * The classified `services/` tree — services at any depth, the subsystems\n * grouping them, and the walk's own findings (`subsystem.*`). The walk itself\n * lives in `./tree/walk.ts` and never imports back into this package; this\n * function is where its two injected dependencies are built — the docs-repo\n * precondition and the artifact-name table `paths.ts` owns.\n */\nexport async function listFleetTree(docsDir: DocsDir, context?: FleetContext): Promise<FleetTree> {\n  if (context !== undefined) return context.fleetTree(docsDir);\n  requireDocsRepo(docsDir, [\"ok\"]);\n  return walkServicesTree({ docsDir, isServiceArtifact: isServiceArtifactName });\n}\n\n/** Every service in the docs repo, at any depth of the tree, ordered by id. */\nexport async function listServices(docsDir: DocsDir, context?: FleetContext): Promise<ServiceEntry[]> {\n  if (context !== undefined) return context.listServices(docsDir);\n  return serviceEntries(await listFleetTree(docsDir));\n}\n\n/**\n * The full entries for a walked tree — frontmatter, artifact presence, ADR\n * count. Split from `listServices` so `FleetContext` can derive its services\n * memo from its tree memo: one walk per invocation answers both questions.\n * Ordering is `compareIds` over the id wherever the service sits — placement\n * is never part of any identity, and `--json` consumers diff this order — with\n * the directory as the tiebreak so a duplicated id (its own error finding)\n * still lists deterministically.\n */\n/**\n * The second spec axis's header, or an empty one when nobody could read it.\n *\n * `readFrontmatter` folds a decode failure into a flag but still THROWS when\n * the path exists and cannot be read as a file at all — a directory named\n * `arch.spec.md`, which test/gate-command.test.ts builds on purpose. This is\n * the fleet ENUMERATION, where one service's bad byte must cost one subject\n * and not the listing of the other 119, so the throw stops here.\n *\n * The distinction between \"no scope\" and \"nobody could look\" is not lost by\n * swallowing it: a path that exists and cannot be read is `service.unreadable`\n * — an ERROR that fails `loam validate` and `loam gate` — which is a louder\n * signal than any row of a listing, and it names the file this cannot.\n */\nasync function archHeader(path: string): Promise<Frontmatter> {\n  try {\n    return await readFrontmatter(path);\n  } catch {\n    return { present: false, malformed: false, data: {}, body: \"\" };\n  }\n}\n\n/**\n * The spec files whose body moved under their vouch — `content.stale`'s\n * question, asked through the one predicate `loam validate` grades with\n * (`movedUnderVouch`) so the fleet listing and the finding cannot disagree\n * about one file. Only a header that carries a stamp (`contentStamp`) costs the\n * second read: the frontmatter read already answered whether there is anything\n * to compare, and on a fleet mid-adoption most headers do not. The body is\n * read exactly as the finding reads it, as UTF-8 text, because the stamp is\n * byte-exact.\n */\nasync function filesMovedUnderVouch(\n  axes: readonly { file: string; path: string; header: Frontmatter }[],\n): Promise<string[]> {\n  const moved = await Promise.all(\n    axes.map(async ({ file, path, header }) =>\n      contentStamp(header) !== undefined && movedUnderVouch(header, await readFile(path, \"utf8\")) ? [file] : [],\n    ),\n  );\n  return moved.flat();\n}\n\n/**\n * `ServiceEntry.adoption`, read off one living spec.md's frontmatter — the one\n * spelling of the marker's test, for the enumeration below and for the adopt\n * brief, which must not call a partial adoption finished. Any value but\n * `partial` reads as absent (SCHEMA.md).\n */\nexport function adoptionOf(fm: Frontmatter): \"partial\" | null {\n  return stringField(fm, \"adoption\") === \"partial\" ? \"partial\" : null;\n}\n\n/** `adoptionOf` for a spec.md by path; an absent file is no marker. */\nexport async function specAdoption(specPath: string): Promise<\"partial\" | null> {\n  return adoptionOf(await readFrontmatter(specPath));\n}\n\nexport async function serviceEntries(tree: FleetTree): Promise<ServiceEntry[]> {\n  const entries = await Promise.all(\n    tree.services.map(async (svc): Promise<ServiceEntry> => {\n      const p = servicePathsAt(svc.dir);\n      // Both spec axes, because a sample is per FILE: one `--sample 3` run can\n      // read a short spec.md in full and stamp a scope on a long arch.spec.md\n      // beside it, and a fleet row that reported only spec.md's header would\n      // print that service as fully vouched while `loam validate` reported it\n      // sampled. `readFrontmatter` answers \"absent\" for a file that is not\n      // there, so a service without the second axis pays one existsSync.\n      const [fm, archFm] = await Promise.all([readFrontmatter(p.spec), archHeader(p.archSpec)]);\n      const headers = { spec: fm, archSpec: archFm };\n      const idProblem = serviceIdProblem(svc.id, \"directory name\");\n      return {\n        id: svc.id,\n        dir: svc.dir,\n        subsystem: svc.subsystem,\n        ...(idProblem === null ? {} : { idProblem }),\n        has: {\n          model: existsSync(p.model),\n          spec: existsSync(p.spec),\n          openapi: existsSync(p.openapi),\n          asyncapi: existsSync(p.asyncapi),\n          runbook: existsSync(p.runbook),\n          health: existsSync(p.health),\n        },\n        adrs: await countMarkdown(p.adrsDir),\n        status: stringField(fm, \"status\") ?? null,\n        adoption: adoptionOf(fm),\n        sources: {\n          declared: listField(fm, \"sources\").length > 0,\n          stamped: stringField(fm, \"sources_digest\") !== undefined,\n        },\n        // Either axis makes the SERVICE sampled, and presence is the test, not\n        // decodability: an unreadable scope is still a stamped partial read\n        // (core/provenance/sample/scope.ts's `readVouchScope`), and the fleet\n        // listing is the last place a mangled field should be able to buy\n        // itself a full-trust row.\n        vouchScope: [fm, archFm].some((header) => readVouchScope(header).kind !== \"none\") ? \"sampled\" : null,\n        // Both axes again, for the scope's reason: a stamp is per FILE, and an\n        // arch.spec.md edited under its vouch is a service part of whose\n        // documentation nobody has re-read.\n        contentStale: await filesMovedUnderVouch(\n          SPEC_AXES.map((axis) => ({ file: axis.file, path: p[axis.key], header: headers[axis.key] })),\n        ),\n      };\n    }),\n  );\n  return entries.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dir, b.dir));\n}\n\n/**\n * How many fleet-level ADRs `architecture/adrs/` holds — the same number, by the\n * same rule (`countMarkdown`), that `ServiceEntry.adrs` carries one altitude\n * down. One shape for one question: a second spelling of \"count the decisions\"\n * is how `list` and `show` once reported different ADR counts for one service.\n *\n * A count and never a finding. The directory is optional, an absent one is 0,\n * and nothing in loam grades either — see `fleetAdrsDir` for why that is the\n * whole design rather than an unfinished half of it. No `FleetContext` overload:\n * one caller asks this once per invocation, and a memo whose key is the docsDir\n * would be a cache nobody reads twice.\n */\nexport async function fleetAdrCount(docsDir: DocsDir): Promise<number> {\n  return countMarkdown(fleetAdrsDir(docsDir));\n}\n\n/**\n * What a feature is CALLED, for a person: intent.md's `title:`, else its first\n * `# ` heading with the feature id peeled off the front, else null.\n *\n * Every row that names a feature used to print the id alone, and an id is a\n * key, not a name — a newcomer looking at `ready  FEAT-101` could not tell\n * which change it was without opening the directory. Read on demand rather\n * than carried on `FeatureEntry`, because the enumeration runs under every\n * command and only the views a person reads need the words. A missing or\n * unreadable intent.md is simply no title: the row still prints its id, and\n * whether intent.md is owed is `status`'s question, not this one's.\n */\nexport async function featureTitle(feature: FeatureEntry): Promise<string | null> {\n  let fm: Frontmatter;\n  try {\n    fm = await readFrontmatter(featurePaths(feature.dir).intent);\n  } catch {\n    // A directory in intent.md's place, a permission: unreadable is no title.\n    // `readFrontmatter` folds only the encoding failure into a flag, and before\n    // this read the views that print a title never opened intent.md at all —\n    // so letting the error escape would hand `loam status` and `loam list`\n    // whole to `repository-unavailable` over a label. Whether intent.md is\n    // fine is the intent row's and `validate`'s question.\n    return null;\n  }\n  const declared = stringField(fm, \"title\")?.trim();\n  if (declared !== undefined && declared !== \"\") return declared;\n  const heading = fm.body.split(/\\r?\\n/).find((l) => l.startsWith(\"# \"));\n  if (heading === undefined) return null;\n  const words = heading.slice(2).trim();\n  const bare = words.startsWith(feature.id) ? words.slice(feature.id.length).replace(/^[\\s:—–-]+/, \"\") : words;\n  return bare === \"\" ? null : bare;\n}\n\nasync function readFeature(dir: FeatureDir, dirName: string, archived: boolean): Promise<FeatureEntry> {\n  const p = featurePaths(dir);\n  return {\n    id: featureIdFromDirName(dirName),\n    dirName,\n    dir,\n    archived,\n    services: (await subdirs(p.specsDir)).map(rawServiceId),\n    has: { intent: existsSync(p.intent), delta: existsSync(p.delta) },\n  };\n}\n\n/**\n * Features in the docs repo, ordered by id (active and archived interleaved when\n * both are asked for). `features/archive/` is the archive, never a feature.\n */\nexport async function listFeatures(\n  docsDir: DocsDir,\n  opts: { includeArchived?: boolean } = {},\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  if (context !== undefined) return context.listFeatures(docsDir, opts);\n  // \"no-services\" is tolerated here on purpose: a docs repo whose services/ is\n  // gone is broken, but it is `listServices` (and `loam doctor`) that says so.\n  // Refusing here too would turn one diagnosis into two contradictory ones.\n  requireDocsRepo(docsDir, [\"ok\", \"no-services\"]);\n  const root = featuresDir(docsDir);\n  const active = (await subdirs(root)).filter((n) => n !== ARCHIVE_DIR);\n  // Branded at the join: the name came off this readdir, onto the features\n  // root it was listed under — the provenance `FeatureDir` records.\n  const out = await Promise.all(active.map((n) => readFeature(featureDirOf(join(root, n)), n, false)));\n\n  if (opts.includeArchived) {\n    const archiveRoot = join(root, ARCHIVE_DIR);\n    const archived = await subdirs(archiveRoot);\n    out.push(...(await Promise.all(archived.map((n) => readFeature(featureDirOf(join(archiveRoot, n)), n, true)))));\n  }\n\n  return out.sort((a, b) => compareIds(a.id, b.id) || compareIds(a.dirName, b.dirName));\n}\n\n/**\n * Which side of `features/archive/` a lookup may land on. The policy is an\n * argument, not a default, so every command's stance on shipped features is\n * visible at its call site: delta/validate/archive work on in-flight features\n * (\"exclude\"), show/verify/new read shipped ones too (\"include\"), unarchive\n * takes back nothing else (\"only\").\n */\nexport type ArchivedPolicy = \"exclude\" | \"include\" | \"only\";\n\n/**\n * Resolve a feature argument — a canonical id (`FEAT-5`) or an exact directory\n * name (`FEAT-5-slug`) — to its entry. The entry's `id` is the canonical\n * spelling, and it is the only name a caller may use from here on: tag filters,\n * coherence, and the cross-feature self-exclusion scans all compare against\n * `feature.id`, never against the raw argument.\n *\n * Matching is EXACT, on one of two spellings: the directory name as it is on\n * disk, or the canonical id derived from it. It used to also match any dirName\n * starting with `arg + \"-\"`, which made the argument a prefix query in\n * disguise: with FEAT-401 and FEAT-402 in flight, `loam archive FEAT` archived\n * whichever sorted first, and `loam delta billing` reached into\n * `billing-7-rewrite`. A destructive command must never pick a target the\n * caller did not name, so a prefix now resolves to nothing at all.\n *\n * An exact directory name still wins over the id spelling (`FEAT-5` the\n * directory over `FEAT-5-slug`, whose id is also `FEAT-5`), and under \"include\"\n * an active feature wins over an archived one. Ties among equally-exact\n * candidates go to the first by name — deterministic, unlike the raw readdir\n * order this replaces; `featureCandidates` returns every one of them, for a\n * caller that must see the tie (`loam status` names the colliding directories).\n */\nexport async function resolveFeature(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry | null> {\n  return (await featureCandidates(docsDir, arg, archived, context))[0] ?? null;\n}\n\n/**\n * Every feature the argument names exactly, best first. Split out of\n * `resolveFeature` so a caller that wants to REFUSE an ambiguous argument can\n * see the tie instead of inheriting the winner.\n */\nexport async function featureCandidates(\n  docsDir: DocsDir,\n  arg: string,\n  archived: ArchivedPolicy,\n  context?: FleetContext,\n): Promise<FeatureEntry[]> {\n  const all = await listFeatures(docsDir, { includeArchived: archived !== \"exclude\" }, context);\n  return all\n    .filter((f) => archived === \"include\" || f.archived === (archived === \"only\"))\n    .filter((f) => f.dirName === arg || f.id === arg)\n    .sort(\n      (a, b) =>\n        Number(b.dirName === arg) - Number(a.dirName === arg) ||\n        Number(a.archived) - Number(b.archived) ||\n        compareIds(a.dirName, b.dirName),\n    );\n}\n\n/**\n * The message for an exclude-mode miss. When the feature exists under\n * `features/archive/`, \"no feature\" is a lie the caller would have to debug —\n * the honest answer is \"already archived\", plus how to look at it. The `--json`\n * code stays `unknown-target` either way: the target is unknown to the command\n * that asked, and the prose carries the diagnosis.\n */\nexport async function missingFeatureMessage(\n  docsDir: DocsDir,\n  arg: string,\n  context?: FleetContext,\n): Promise<string> {\n  const shipped = await resolveFeature(docsDir, arg, \"only\", context);\n  if (shipped !== null) {\n    return (\n      `Feature '${shipped.id}' is already archived (features/archive/${shipped.dirName}) — ` +\n      `\\`loam show ${shipped.id}\\` reads it, \\`loam unarchive ${shipped.id}\\` re-opens it.`\n    );\n  }\n  return `No feature '${arg}' under ${featuresDir(docsDir)}.`;\n}\n"]}

package/dist/core/repo/service-target.js

@@ -0,0 +1,153 @@
+/**
+ * Turning a name a caller typed into a name loam may join into a path.
+ *
+ * `unfiledServicePaths(docsDir, name)` spells `<docsDir>/services/<name>/`,
+ * and its parameter is `PathableService`: an unchecked name at that call site
+ * no longer compiles, and this module is where a name a caller typed EARNS the
+ * type. The history is why it exists. Six commands guard their argument with
+ * `assertServiceId` at the boundary; `validate` never did, and both of its
+ * entry points — `--service <id>` and the positional `<target>` — reached
+ * the path builder with whatever argv held. `--service ../../outside/services/x`
+ * resolved ABOVE the docs repo, and where a `spec.md` happened to sit there
+ * loam opened it, graded it, and reported its frontmatter through `--json`.
+ *
+ * The grammar alone is not the answer, and this is the whole reason this module
+ * exists rather than a call to `assertServiceId`. `services/Payment Service/`
+ * is a directory `loam list` shows, `validate --all` grades, and
+ * `service.id-invalid` calls an error nobody can fix without a rename — so it
+ * is exactly the directory somebody points `validate --service` at. Refusing on
+ * the grammar would make the one service loam complains about the one service
+ * loam cannot look at.
+ *
+ * So the enumeration answers first and the grammar answers second:
+ *
+ *   in `services/`      → the enumeration's OWN id, which is a name loam
+ *                         already reads off disk every time it lists the fleet.
+ *                         Legal or not, it exists, and joining it lands where
+ *                         the directory is.
+ *   not there, legal    → the caller's name. Nothing exists yet; the run
+ *                         continues and grades it `service.unknown`, with the
+ *                         near-miss hints that make a typo diagnosable.
+ *   not there, illegal  → refused, before any path is built.
+ *
+ * `show` and `status` already resolve against the enumeration this way. What
+ * they do not do is fall through to the grammar, which is why they answer
+ * "no such service" to a name that could never BE a service — a worse sentence
+ * for the same input.
+ */
+import { listServices } from "./repo.js";
+import { parseServiceId } from "../kernel/ids/service.js";
+import { serviceTreePath } from "../kernel/ids/dirs.js";
+import { servicePathsAt, unfiledServicePaths } from "./paths.js";
+/**
+ * The enumerated services, or the empty list when `services/` cannot be
+ * enumerated at all. The swallow is deliberate and spelled ONCE: every
+ * repository-aware resolver wants "which services exist" as context, and an
+ * unenumerable `services/` is that repository's own diagnosis
+ * (`services-missing`), never the asking check's. Six call sites each carried
+ * this try/catch in their own spelling before it lived here — which is exactly
+ * the shape docs/CODE-STYLE.md warns about: an errno fix lands in one copy and
+ * the other five keep the old behaviour. The existence probes that used to ask
+ * `existsSync(services/<id>/)` ask membership HERE for the same tolerance:
+ * `validate --feature` must run in a docs repo with no `services/` at all,
+ * where enumerating is a refusal but "does this service exist" still has the
+ * honest answer no.
+ */
+export async function enumeratedServices(docsDir, fleet) {
+    try {
+        return await listServices(docsDir, fleet);
+    }
+    catch {
+        return [];
+    }
+}
+/** The id projection of `enumeratedServices` — most membership asks want only the names. */
+export async function enumeratedServiceIds(docsDir, fleet) {
+    return (await enumeratedServices(docsDir, fleet)).map((s) => s.id);
+}
+/**
+ * The artifact paths of a service wherever it lives: the enumeration's own
+ * directory when the id exists anywhere in the tree, the unfiled root
+ * spelling otherwise — so an absent service still probes, grades
+ * (`service.unknown`) and CREATES exactly as it did when the tree was flat.
+ * This is the one bridge the ~40 former `servicePaths` call sites resolve
+ * through — and it is NOT free: without a `fleet` context every call is a
+ * fresh fleet enumeration (one readdir per directory walked plus a
+ * frontmatter read and several existence probes per service), which measured
+ * ~13 ms per call on a 120-service fleet. A call site inside a loop must
+ * thread the command's `FleetContext`; a caller that already holds a
+ * `ServiceEntry` should spell `servicePathsAt(entry.dir)` directly and pay
+ * nothing.
+ */
+/**
+ * Where a service sits under `services/`, repo-relative and WITHOUT a trailing
+ * slash — for a message that names an existing directory to a reader.
+ *
+ * The join it replaces is `services/${id}`, which is right for an unfiled
+ * service and wrong for every filed one; `paths.ts` states the same rule for
+ * artifact paths and this is its display sibling. A name the enumeration does
+ * not answer to falls back to the unfiled spelling, which is the only honest
+ * answer: there is no directory to point at, and that is usually what the
+ * message is about.
+ */
+export async function serviceTreePathOf(docsDir, service, fleet) {
+    const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);
+    return entry === undefined ? `services/${service}` : serviceTreePath(entry);
+}
+export async function locateServicePaths(docsDir, service, fleet) {
+    const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);
+    return entry === undefined ? unfiledServicePaths(docsDir, service) : servicePathsAt(entry.dir);
+}
+export async function resolveServiceTarget(docsDir, name, label, fleet) {
+    // The enumeration is asked first, and its answer is the value that travels
+    // on: `entry.id` rather than `name`. They are equal as strings, and only one
+    // of them carries the fact that a `readdir` produced it. The resolved `dir`
+    // travels too, so a caller that goes on to read artifacts can spell
+    // `servicePathsAt(dir)` without a second enumeration; it is absent exactly
+    // when the name resolved by grammar alone — nothing exists to point at.
+    const entry = (await listServices(docsDir, fleet)).find((s) => s.id === name);
+    if (entry !== undefined)
+        return { ok: true, id: entry.id, dir: entry.dir };
+    return parseServiceId(name, label);
+}
+/**
+ * The same resolution for a name a DOCUMENT declared — an edge target's
+ * `metadata { service '…' }` binding, or its title standing in for one — where
+ * the caller needs an answer instead of a refusal: which enumerated directory,
+ * if any, does this text name?
+ *
+ * The enumeration is the fleet's `services/` plus whatever directory names the
+ * caller has already read for itself — a feature's own `specs/<svc>/`, the only
+ * place a service the feature INTRODUCES has a directory at all. There is
+ * deliberately no grammar arm here, in either direction: `services/Payment
+ * Service/` keeps resolving for the banner's reason, and a legal-looking name
+ * that matches no directory has no living file anywhere, so the caller's
+ * business is to grade it absent — never to build a path from it.
+ *
+ * The index is built on the first ask, not at construction: coherence asks per
+ * op-edge and features routinely carry none, so the enumeration only runs once
+ * an answer matters. A repo whose `services/` cannot be enumerated resolves
+ * only the caller's own names — every living probe would have found nothing
+ * there anyway, and `services-missing` is that repository's diagnosis, not
+ * this document's.
+ */
+export function enumeratedServiceIndex(docsDir, known, fleet) {
+    let index;
+    return async (name) => {
+        if (index === undefined) {
+            index = new Map();
+            for (const id of known)
+                index.set(id, id);
+            try {
+                for (const s of await listServices(docsDir, fleet))
+                    index.set(s.id, s.id);
+            }
+            catch {
+                // The docblock's last paragraph: no enumerable services/ means the
+                // fleet half of the index is empty, not that the question is an error.
+            }
+        }
+        return index.get(name);
+    };
+}
+//# sourceMappingURL=service-target.js.map

package/dist/core/repo/service-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-target.js","sourceRoot":"","sources":["../../../src/core/repo/service-target.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Turning a name a caller typed into a name loam may join into a path.\n *\n * `unfiledServicePaths(docsDir, name)` spells `<docsDir>/services/<name>/`,\n * and its parameter is `PathableService`: an unchecked name at that call site\n * no longer compiles, and this module is where a name a caller typed EARNS the\n * type. The history is why it exists. Six commands guard their argument with\n * `assertServiceId` at the boundary; `validate` never did, and both of its\n * entry points — `--service <id>` and the positional `<target>` — reached\n * the path builder with whatever argv held. `--service ../../outside/services/x`\n * resolved ABOVE the docs repo, and where a `spec.md` happened to sit there\n * loam opened it, graded it, and reported its frontmatter through `--json`.\n *\n * The grammar alone is not the answer, and this is the whole reason this module\n * exists rather than a call to `assertServiceId`. `services/Payment Service/`\n * is a directory `loam list` shows, `validate --all` grades, and\n * `service.id-invalid` calls an error nobody can fix without a rename — so it\n * is exactly the directory somebody points `validate --service` at. Refusing on\n * the grammar would make the one service loam complains about the one service\n * loam cannot look at.\n *\n * So the enumeration answers first and the grammar answers second:\n *\n *   in `services/`      → the enumeration's OWN id, which is a name loam\n *                         already reads off disk every time it lists the fleet.\n *                         Legal or not, it exists, and joining it lands where\n *                         the directory is.\n *   not there, legal    → the caller's name. Nothing exists yet; the run\n *                         continues and grades it `service.unknown`, with the\n *                         near-miss hints that make a typo diagnosable.\n *   not there, illegal  → refused, before any path is built.\n *\n * `show` and `status` already resolve against the enumeration this way. What\n * they do not do is fall through to the grammar, which is why they answer\n * \"no such service\" to a name that could never BE a service — a worse sentence\n * for the same input.\n */\nimport { listServices } from \"./repo.js\";\nimport { parseServiceId, type PathableService, type RawServiceId } from \"../kernel/ids/service.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { serviceTreePath, type DocsDir, type ServiceDir } from \"../kernel/ids/dirs.js\";\nimport { servicePathsAt, unfiledServicePaths, type ServicePaths } from \"./paths.js\";\nimport type { ServiceEntry } from \"./entries.js\";\n\nexport type ServiceTarget =\n  | { readonly ok: true; readonly id: RawServiceId; readonly dir?: ServiceDir }\n  | { readonly ok: false; readonly problem: string };\n\n/**\n * The enumerated services, or the empty list when `services/` cannot be\n * enumerated at all. The swallow is deliberate and spelled ONCE: every\n * repository-aware resolver wants \"which services exist\" as context, and an\n * unenumerable `services/` is that repository's own diagnosis\n * (`services-missing`), never the asking check's. Six call sites each carried\n * this try/catch in their own spelling before it lived here — which is exactly\n * the shape docs/CODE-STYLE.md warns about: an errno fix lands in one copy and\n * the other five keep the old behaviour. The existence probes that used to ask\n * `existsSync(services/<id>/)` ask membership HERE for the same tolerance:\n * `validate --feature` must run in a docs repo with no `services/` at all,\n * where enumerating is a refusal but \"does this service exist\" still has the\n * honest answer no.\n */\nexport async function enumeratedServices(\n  docsDir: DocsDir,\n  fleet?: FleetContext,\n): Promise<ServiceEntry[]> {\n  try {\n    return await listServices(docsDir, fleet);\n  } catch {\n    return [];\n  }\n}\n\n/** The id projection of `enumeratedServices` — most membership asks want only the names. */\nexport async function enumeratedServiceIds(\n  docsDir: DocsDir,\n  fleet?: FleetContext,\n): Promise<RawServiceId[]> {\n  return (await enumeratedServices(docsDir, fleet)).map((s) => s.id);\n}\n\n/**\n * The artifact paths of a service wherever it lives: the enumeration's own\n * directory when the id exists anywhere in the tree, the unfiled root\n * spelling otherwise — so an absent service still probes, grades\n * (`service.unknown`) and CREATES exactly as it did when the tree was flat.\n * This is the one bridge the ~40 former `servicePaths` call sites resolve\n * through — and it is NOT free: without a `fleet` context every call is a\n * fresh fleet enumeration (one readdir per directory walked plus a\n * frontmatter read and several existence probes per service), which measured\n * ~13 ms per call on a 120-service fleet. A call site inside a loop must\n * thread the command's `FleetContext`; a caller that already holds a\n * `ServiceEntry` should spell `servicePathsAt(entry.dir)` directly and pay\n * nothing.\n */\n/**\n * Where a service sits under `services/`, repo-relative and WITHOUT a trailing\n * slash — for a message that names an existing directory to a reader.\n *\n * The join it replaces is `services/${id}`, which is right for an unfiled\n * service and wrong for every filed one; `paths.ts` states the same rule for\n * artifact paths and this is its display sibling. A name the enumeration does\n * not answer to falls back to the unfiled spelling, which is the only honest\n * answer: there is no directory to point at, and that is usually what the\n * message is about.\n */\nexport async function serviceTreePathOf(\n  docsDir: DocsDir,\n  service: string,\n  fleet?: FleetContext,\n): Promise<string> {\n  const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);\n  return entry === undefined ? `services/${service}` : serviceTreePath(entry);\n}\n\nexport async function locateServicePaths(\n  docsDir: DocsDir,\n  service: PathableService,\n  fleet?: FleetContext,\n): Promise<ServicePaths> {\n  const entry = (await enumeratedServices(docsDir, fleet)).find((s) => s.id === service);\n  return entry === undefined ? unfiledServicePaths(docsDir, service) : servicePathsAt(entry.dir);\n}\n\nexport async function resolveServiceTarget(\n  docsDir: DocsDir,\n  name: string,\n  label: string,\n  fleet?: FleetContext,\n): Promise<ServiceTarget> {\n  // The enumeration is asked first, and its answer is the value that travels\n  // on: `entry.id` rather than `name`. They are equal as strings, and only one\n  // of them carries the fact that a `readdir` produced it. The resolved `dir`\n  // travels too, so a caller that goes on to read artifacts can spell\n  // `servicePathsAt(dir)` without a second enumeration; it is absent exactly\n  // when the name resolved by grammar alone — nothing exists to point at.\n  const entry = (await listServices(docsDir, fleet)).find((s) => s.id === name);\n  if (entry !== undefined) return { ok: true, id: entry.id, dir: entry.dir };\n  return parseServiceId(name, label);\n}\n\n/**\n * The same resolution for a name a DOCUMENT declared — an edge target's\n * `metadata { service '…' }` binding, or its title standing in for one — where\n * the caller needs an answer instead of a refusal: which enumerated directory,\n * if any, does this text name?\n *\n * The enumeration is the fleet's `services/` plus whatever directory names the\n * caller has already read for itself — a feature's own `specs/<svc>/`, the only\n * place a service the feature INTRODUCES has a directory at all. There is\n * deliberately no grammar arm here, in either direction: `services/Payment\n * Service/` keeps resolving for the banner's reason, and a legal-looking name\n * that matches no directory has no living file anywhere, so the caller's\n * business is to grade it absent — never to build a path from it.\n *\n * The index is built on the first ask, not at construction: coherence asks per\n * op-edge and features routinely carry none, so the enumeration only runs once\n * an answer matters. A repo whose `services/` cannot be enumerated resolves\n * only the caller's own names — every living probe would have found nothing\n * there anyway, and `services-missing` is that repository's diagnosis, not\n * this document's.\n */\nexport function enumeratedServiceIndex(\n  docsDir: DocsDir,\n  known: readonly RawServiceId[],\n  fleet?: FleetContext,\n): (name: string) => Promise<RawServiceId | undefined> {\n  let index: Map<string, RawServiceId> | undefined;\n  return async (name: string): Promise<RawServiceId | undefined> => {\n    if (index === undefined) {\n      index = new Map<string, RawServiceId>();\n      for (const id of known) index.set(id, id);\n      try {\n        for (const s of await listServices(docsDir, fleet)) index.set(s.id, s.id);\n      } catch {\n        // The docblock's last paragraph: no enumerable services/ means the\n        // fleet half of the index is empty, not that the question is an error.\n      }\n    }\n    return index.get(name);\n  };\n}\n"]}

package/dist/core/repo/state.js

@@ -0,0 +1,58 @@
+/**
+ * Is there a docs repo there at all?
+ *
+ * Three answers, not two: missing, present-but-empty, and ok. The middle one
+ * exists because a freshly cloned docs repo whose `services/` git never tracked
+ * looks identical to a directory nobody wired — and the fix differs.
+ */
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+export function docsRepoState(docsDir) {
+    const path = docsDir;
+    let isDir = false;
+    try {
+        isDir = statSync(path).isDirectory();
+    }
+    catch {
+        isDir = false;
+    }
+    if (!isDir)
+        return { kind: "missing", path };
+    return { kind: existsSync(join(path, "services")) ? "ok" : "no-services", path };
+}
+/**
+ * The docs repo is not there. Thrown rather than returned because every caller
+ * of the enumeration wants the same thing — to stop — and a `[]` return is the
+ * bug this closes. `message` is written for a human at a terminal: the CLI's
+ * top-level handler prints it verbatim, and commands that catch it report
+ * `repository-unavailable`.
+ */
+export class DocsRepoUnavailableError extends Error {
+    state;
+    constructor(state, message) {
+        super(message);
+        this.state = state;
+        this.name = "DocsRepoUnavailableError";
+    }
+}
+/**
+ * Refuse to enumerate a docs repo that is not one. `allow` names the states the
+ * caller can honestly survive: features/ may be absent from a real docs repo
+ * (nothing is in flight yet), so feature enumeration only insists the docs repo
+ * EXISTS, while service enumeration insists it is shaped like a docs repo — a
+ * `services/` directory is what makes it one.
+ */
+export function requireDocsRepo(docsDir, allow) {
+    const state = docsRepoState(docsDir);
+    if (allow.includes(state.kind))
+        return;
+    if (state.kind === "missing") {
+        throw new DocsRepoUnavailableError(state, `The configured docs repo does not exist: ${state.path}. ` +
+            "Fix `docsDir` in loam.json, clone the docs repo there, " +
+            "or run `loam init --docs <dir> --create` to make a new one.");
+    }
+    throw new DocsRepoUnavailableError(state, `${state.path} is not a docs repo — it has no services/ directory. ` +
+        "Point `docsDir` in loam.json at the shared docs repo, " +
+        "or run `loam init --docs <dir> --create` to make one.");
+}
+//# sourceMappingURL=state.js.map

package/dist/core/repo/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/repo/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8BjC,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,IAAI,GAAG,OAAO,CAAC;IACrB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,KAAK,GAAG,KAAK,CAAC;IAChB,CAAC;IACD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC7C,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IAEtC,KAAK;IADhB,YACW,KAAoB,EAC7B,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;qBAHN,KAAK;QAId,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe,EAAE,KAAqB;IACpE,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,wBAAwB,CAChC,KAAK,EACL,4CAA4C,KAAK,CAAC,IAAI,IAAI;YACxD,yDAAyD;YACzD,6DAA6D,CAChE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,wBAAwB,CAChC,KAAK,EACL,GAAG,KAAK,CAAC,IAAI,uDAAuD;QAClE,wDAAwD;QACxD,uDAAuD,CAC1D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Is there a docs repo there at all?\n *\n * Three answers, not two: missing, present-but-empty, and ok. The middle one\n * exists because a freshly cloned docs repo whose `services/` git never tracked\n * looks identical to a directory nobody wired — and the fix differs.\n */\nimport { existsSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\n\n/* ------------------------------------------------------------------ */\n/* Is there a docs repo there at all?                                  */\n/* ------------------------------------------------------------------ */\n\n/**\n * What is actually at `docsDir`. Three answers, because they point at three\n * different fixes and the enumeration below used to give all of them the same\n * one — an empty list:\n *\n *  - `missing`     — nothing there (or not a directory): `docsDir` in loam.json\n *                    is wrong, or the docs repo was never cloned;\n *  - `no-services` — a directory, but with no `services/`: it is some other\n *                    directory, most often the service repo itself after a typo;\n *  - `ok`          — a docs repo. `services/` may still be EMPTY, and that is a\n *                    legitimate state: a docs repo before the first `loam adopt`.\n *\n * \"Empty fleet\" and \"wrong path\" are the same output only if nobody asks this\n * question, and a green `loam list` over a docsDir that does not exist is worse\n * than a red one: it says the fleet is fine.\n */\nexport type DocsRepoKind = \"missing\" | \"no-services\" | \"ok\";\n\nexport interface DocsRepoState {\n  kind: DocsRepoKind;\n  /** The path examined, so a caller can quote it without re-deriving it. */\n  path: string;\n}\n\nexport function docsRepoState(docsDir: string): DocsRepoState {\n  const path = docsDir;\n  let isDir = false;\n  try {\n    isDir = statSync(path).isDirectory();\n  } catch {\n    isDir = false;\n  }\n  if (!isDir) return { kind: \"missing\", path };\n  return { kind: existsSync(join(path, \"services\")) ? \"ok\" : \"no-services\", path };\n}\n\n/**\n * The docs repo is not there. Thrown rather than returned because every caller\n * of the enumeration wants the same thing — to stop — and a `[]` return is the\n * bug this closes. `message` is written for a human at a terminal: the CLI's\n * top-level handler prints it verbatim, and commands that catch it report\n * `repository-unavailable`.\n */\nexport class DocsRepoUnavailableError extends Error {\n  constructor(\n    readonly state: DocsRepoState,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"DocsRepoUnavailableError\";\n  }\n}\n\n/**\n * Refuse to enumerate a docs repo that is not one. `allow` names the states the\n * caller can honestly survive: features/ may be absent from a real docs repo\n * (nothing is in flight yet), so feature enumeration only insists the docs repo\n * EXISTS, while service enumeration insists it is shaped like a docs repo — a\n * `services/` directory is what makes it one.\n */\nexport function requireDocsRepo(docsDir: string, allow: DocsRepoKind[]): void {\n  const state = docsRepoState(docsDir);\n  if (allow.includes(state.kind)) return;\n  if (state.kind === \"missing\") {\n    throw new DocsRepoUnavailableError(\n      state,\n      `The configured docs repo does not exist: ${state.path}. ` +\n        \"Fix `docsDir` in loam.json, clone the docs repo there, \" +\n        \"or run `loam init --docs <dir> --create` to make a new one.\",\n    );\n  }\n  throw new DocsRepoUnavailableError(\n    state,\n    `${state.path} is not a docs repo — it has no services/ directory. ` +\n      \"Point `docsDir` in loam.json at the shared docs repo, \" +\n      \"or run `loam init --docs <dir> --create` to make one.\",\n  );\n}\n"]}