@intentius/chant 0.80.0 → 0.81.0

package/src/workspace/ls-contract.test.ts

@@ -0,0 +1,200 @@
+/**
+ * The read contract for `chant workspace ls --json` (#2534, #2524 D15): the
+ * output schema is a valid draft 2020-12 document, its closed code lists match
+ * the code, and real output validates against it, for the chant repo's own
+ * declaration (#2557) and for small workspaces built here.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import Ajv2020 from "ajv/dist/2020";
+import { afterAll, describe, expect, test } from "vitest";
+import { WORKSPACE_ERROR_CODES } from "./declaration";
+import { GROUP_REASON_CODES, listWorkspace, LS_CONTRACT_VERSION, LS_OUTPUT_SCHEMA_ID, MEMBER_REASON_CODES, type LsDocument } from "./ls";
+import schema from "./ls.schema.json";
+
+const REPO = join(import.meta.dirname, "..", "..", "..", "..");
+
+const ajv = new Ajv2020({ strict: true, allErrors: true });
+const validate = ajv.compile(schema);
+
+function expectValid(doc: LsDocument): void {
+  const ok = validate(doc);
+  expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+}
+
+function result(doc: LsDocument): Extract<LsDocument, { members: unknown }> {
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+const scratch: string[] = [];
+afterAll(() => {
+  for (const d of scratch) rmSync(d, { recursive: true, force: true });
+});
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", ["-c", "user.name=t", "-c", "user.email=t@example.com", "-c", "commit.gpgsign=false", ...args], {
+    cwd,
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/** A git repository holding `files`. */
+function repo(files: Record<string, string>): string {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-ls-")));
+  scratch.push(root);
+  for (const [path, text] of Object.entries(files)) {
+    mkdirSync(dirname(join(root, path)), { recursive: true });
+    writeFileSync(join(root, path), text);
+  }
+  git(root, "init", "-q");
+  return root;
+}
+
+const declaration = (members: unknown[]) => JSON.stringify({ name: "acme", schema: 1, members }, null, 2);
+
+describe("ls output schema", () => {
+  test("is a valid draft 2020-12 document with the published $id", () => {
+    expect(schema.$schema).toBe("https://json-schema.org/draft/2020-12/schema");
+    expect(ajv.validateSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(LS_OUTPUT_SCHEMA_ID);
+    expect(LS_CONTRACT_VERSION).toBe(1);
+  });
+
+  test("lists exactly the reason and error codes the code can return", () => {
+    expect(schema.$defs.member.properties.reason.oneOf[1].properties!.code.enum).toEqual([...MEMBER_REASON_CODES]);
+    expect(schema.$defs.group.properties.reason.oneOf[1].properties!.code.enum).toEqual([...GROUP_REASON_CODES]);
+    expect(schema.$defs.failure.properties.error.properties.code.enum).toEqual([...WORKSPACE_ERROR_CODES]);
+  });
+});
+
+describe("chant workspace ls on the chant repo (#2557)", () => {
+  const doc = result(listWorkspace({ cwd: join(REPO, "lexicons", "aws", "examples") }));
+
+  test("validates, from any directory below the root, with every member readable", () => {
+    expectValid(doc);
+    expect(doc.workspace).toMatchObject({ name: "chant", root: ".", file: "chant.workspace.json", schema: 1 });
+    expect(doc.members.filter((m) => !m.readable)).toEqual([]);
+  });
+
+  test("declares every package and every lexicon as a member", () => {
+    const dirs = new Set(doc.members.map((m) => m.dir));
+    for (const parent of ["packages", "lexicons"]) {
+      for (const d of readdirSync(join(REPO, parent), { withFileTypes: true })) {
+        if (d.isDirectory()) expect(dirs.has(`${parent}/${d.name}`), `${parent}/${d.name} is not declared in chant.workspace.json`).toBe(true);
+      }
+    }
+  });
+
+  test("declares the examples and fixtures as example groups (ws-051)", () => {
+    expect(doc.groups.map((g) => [g.name, g.glob])).toEqual([
+      ["examples", ["examples/*"]],
+      ["lexicon-examples", ["lexicons/*/examples/*"]],
+      ["fixtures", ["test/forgejo-preview-e2e", "test/leftness"]],
+    ]);
+    for (const g of doc.groups) expect(g.reason, g.name).toBeNull();
+    expect(doc.groups[0].matches).toContain("examples/getting-started");
+    expect(doc.groups[0].skipped).toContain("examples/terraform-carve-out");
+    expect(doc.groups[1].matches).toContain("lexicons/aws/examples/lambda-api");
+  });
+});
+
+describe("chant workspace ls on built workspaces", () => {
+  test("lists a member it can't read with a reason code, and the read still succeeds", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([
+        { name: "web", dir: "apps/web", kind: "chant", roles: [{ name: "frontend", path: "src" }] },
+        { name: "gone", dir: "apps/gone", kind: "chant" },
+        { name: "infra", dir: "infra", kind: "terraform" },
+        { name: "tools", dir: "tools", kind: "chant" },
+        { name: "vendor", dir: "vendor", kind: "other", because: "vendored" },
+        { name: "examples", kind: "examples", glob: "examples/*" },
+      ]),
+      "apps/web/chant.config.ts": "",
+      "infra/main.tf": "",
+      "tools/README.md": "",
+      "vendor/x.txt": "",
+      "examples/README.md": "",
+    });
+    const doc = result(listWorkspace({ cwd: join(root, "apps", "web") }));
+    expectValid(doc);
+    expect(doc.members.map((m) => [m.name, m.readable, m.reason?.code ?? null])).toEqual([
+      ["web", true, null],
+      ["gone", false, "dir-missing"],
+      ["infra", false, "unknown-kind"],
+      ["tools", false, "kind-probe-failed"],
+      ["vendor", true, null],
+    ]);
+    expect(doc.members[2].reason?.message).toMatch(/known kinds: chant, other, workspace/);
+    expect(doc.members[0].roles).toEqual([{ name: "frontend", path: "src" }]);
+    expect(doc.groups[0].reason?.code).toBe("no-matches");
+    expect(doc.summary).toEqual({ members: 5, unreadable: 3, groups: 1, matches: 0 });
+  });
+
+  test("a nested workspace member is readable by its own declaration, and ls inside it lists the inner one", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "kit", dir: "vendor/kit", kind: "workspace" }]),
+      "vendor/kit/chant.workspace.jsonc": "// inner\n" + JSON.stringify({ name: "kit", schema: 1, members: [] }),
+    });
+    expect(result(listWorkspace({ cwd: root })).members[0].readable).toBe(true);
+    expect(result(listWorkspace({ cwd: join(root, "vendor", "kit") })).workspace).toMatchObject({ name: "kit", root: "vendor/kit", file: "chant.workspace.jsonc" });
+  });
+
+  test("every failure validates with its code, and a parse error carries its location", () => {
+    const empty = repo({});
+    const ambiguous = repo({ "chant.workspace.json": declaration([]), "chant.workspace.jsonc": declaration([]) });
+    const broken = repo({ "chant.workspace.json": '{\n  "name": "acme",\n  "schema": 1\n  "members": []\n}\n' });
+    const invalid = repo({ "chant.workspace.json": declaration([{ name: "_members", dir: "a", kind: "chant" }]) });
+    const placement = repo({ "chant.workspace.json": declaration([{ name: "a", dir: "a", kind: "chant" }, { name: "b", dir: "a/b", kind: "chant" }]) });
+    const tooOld = repo({ "chant.workspace.json": JSON.stringify({ name: "acme", schema: 1, minReader: "999.0.0", members: [] }) });
+    const outside = realpathSync(mkdtempSync(join(tmpdir(), "chant-ls-nogit-")));
+    scratch.push(outside);
+    const docs = [
+      listWorkspace({ cwd: empty }),
+      listWorkspace({ cwd: ambiguous }),
+      listWorkspace({ cwd: broken }),
+      listWorkspace({ cwd: invalid }),
+      listWorkspace({ cwd: placement }),
+      listWorkspace({ cwd: tooOld }),
+      listWorkspace({ cwd: outside, at: "HEAD" }),
+      listWorkspace({ cwd: empty, at: "no-such-rev" }),
+    ];
+    for (const doc of docs) expectValid(doc);
+    expect(docs.map((d) => ("error" in d ? d.error.code : "ok"))).toEqual([
+      "declaration-missing",
+      "declaration-ambiguous",
+      "declaration-unparseable",
+      "declaration-invalid",
+      "placement-invalid",
+      "reader-too-old",
+      "not-a-git-repository",
+      "revision-unknown",
+    ]);
+    const parseError = docs[2] as Extract<LsDocument, { error: unknown }>;
+    expect(parseError.error.location).toEqual({ file: "chant.workspace.json", line: 4, column: 3 });
+  });
+
+  test("--at reads the declaration and members from a commit, offline", () => {
+    const root = repo({
+      "chant.workspace.json": declaration([{ name: "web", dir: "web", kind: "chant" }, { name: "ex", kind: "examples", glob: "examples/*" }]),
+      "web/chant.config.ts": "",
+      "examples/one/chant.config.ts": "",
+    });
+    git(root, "add", "-A");
+    git(root, "commit", "-q", "-m", "one");
+    const first = git(root, "rev-parse", "HEAD");
+    // Change the working tree after the commit: --at must not see it.
+    rmSync(join(root, "web"), { recursive: true });
+    writeFileSync(join(root, "chant.workspace.json"), declaration([]));
+    const doc = result(listWorkspace({ cwd: root, at: "HEAD" }));
+    expectValid(doc);
+    expect(doc.at).toBe(first);
+    expect(doc.members.map((m) => [m.name, m.readable])).toEqual([["web", true]]);
+    expect(doc.groups[0].matches).toEqual(["examples/one"]);
+    expect(result(listWorkspace({ cwd: root })).members).toEqual([]);
+  });
+});

package/src/workspace/ls.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json",
+  "title": "chant workspace ls output",
+  "description": "What `chant workspace ls --json` prints, version 1 of the read contract for listing a workspace (#2524 D15, #2534). Readers ignore fields they do not know; a field is only ever added within a version. The reason and error codes are closed lists: a new code is a new contract version. Contract version 1 is written by chant 0.81.0 and newer; a reader that needs it refuses output whose `contract` it doesn't know. Every code is in the one closed list of `reason-codes.ts`.",
+  "oneOf": [{ "$ref": "#/$defs/result" }, { "$ref": "#/$defs/failure" }],
+  "$defs": {
+    "result": {
+      "description": "The declaration was read. Exit code 0, even when some members can't be read.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "at", "workspace", "members", "groups", "summary"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string", "description": "The version of the chant that read the workspace." },
+        "at": {
+          "description": "The full commit id the workspace was read at (--at), or null for the working tree.",
+          "type": ["string", "null"],
+          "pattern": "^[0-9a-f]{40,64}$"
+        },
+        "error": false,
+        "workspace": {
+          "type": "object",
+          "required": ["name", "root", "file", "schema", "minReader", "pins"],
+          "properties": {
+            "name": { "type": "string", "description": "The declared name. With the revision, it identifies the workspace." },
+            "root": {
+              "type": "string",
+              "description": "The workspace root relative to the git root, with / separators, \".\" for the git root itself. An absolute path outside a git repository."
+            },
+            "file": { "enum": ["chant.workspace.json", "chant.workspace.jsonc"] },
+            "schema": { "const": 1 },
+            "minReader": { "type": ["string", "null"] },
+            "pins": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": ["package", "version", "path", "integrity"],
+                "properties": {
+                  "package": { "type": ["string", "null"] },
+                  "version": { "type": ["string", "null"] },
+                  "path": { "type": ["string", "null"] },
+                  "integrity": { "type": ["string", "null"] }
+                }
+              }
+            }
+          }
+        },
+        "members": {
+          "description": "Every member, in declaration order, readable or not.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/member" }
+        },
+        "groups": {
+          "description": "Every example group (ws-051), in declaration order. Their matches are not members.",
+          "type": "array",
+          "items": { "$ref": "#/$defs/group" }
+        },
+        "summary": {
+          "type": "object",
+          "required": ["members", "unreadable", "groups", "matches"],
+          "properties": {
+            "members": { "type": "integer", "minimum": 0 },
+            "unreadable": { "type": "integer", "minimum": 0, "description": "Members with a reason." },
+            "groups": { "type": "integer", "minimum": 0 },
+            "matches": { "type": "integer", "minimum": 0, "description": "Projects across all groups." }
+          }
+        }
+      }
+    },
+    "member": {
+      "type": "object",
+      "required": ["name", "dir", "kind", "roles", "upstream", "because", "readable", "reason"],
+      "properties": {
+        "name": { "type": "string" },
+        "dir": { "type": "string", "description": "Relative to the workspace root, with / separators; \".\" is the root member." },
+        "kind": { "type": "string" },
+        "roles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "path"],
+            "properties": {
+              "name": { "type": "string" },
+              "path": { "type": ["string", "null"], "description": "Relative to the member's directory, or null for the whole member." }
+            }
+          }
+        },
+        "upstream": { "type": ["string", "null"] },
+        "because": { "type": ["string", "null"] },
+        "readable": { "type": "boolean", "description": "True exactly when reason is null." },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["dir-missing", "unknown-kind", "kind-probe-failed"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      },
+      "if": { "type": "object", "properties": { "readable": { "const": true } }, "required": ["readable"] },
+      "then": { "type": "object", "properties": { "reason": { "type": "null" } } },
+      "else": { "type": "object", "properties": { "reason": { "type": "object" } } }
+    },
+    "group": {
+      "type": "object",
+      "required": ["name", "kind", "glob", "matches", "skipped", "reason"],
+      "properties": {
+        "name": { "type": "string" },
+        "kind": { "const": "examples" },
+        "glob": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "matches": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Directories the globs match that hold a chant project, relative to the workspace root, sorted. They are built and linted, and nothing else."
+        },
+        "skipped": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Directories the globs match that hold no chant project. They are left alone."
+        },
+        "reason": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["code", "message"],
+              "properties": {
+                "code": { "enum": ["no-matches"] },
+                "message": { "type": "string" }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "failure": {
+      "description": "The declaration could not be read, and nothing is listed. Exit code 1.",
+      "type": "object",
+      "required": ["$schema", "contract", "chant", "error"],
+      "properties": {
+        "$schema": { "const": "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json" },
+        "contract": { "const": 1 },
+        "chant": { "type": "string" },
+        "error": {
+          "type": "object",
+          "required": ["code", "message", "location"],
+          "properties": {
+            "code": {
+              "enum": [
+                "declaration-missing",
+                "declaration-ambiguous",
+                "declaration-unparseable",
+                "declaration-invalid",
+                "placement-invalid",
+                "reader-too-old",
+                "root-chant-required",
+                "not-a-git-repository",
+                "revision-unknown"
+              ]
+            },
+            "message": { "type": "string" },
+            "location": {
+              "description": "Where in the declaration the problem is, or null when it is not in the file.",
+              "oneOf": [
+                { "type": "null" },
+                {
+                  "type": "object",
+                  "required": ["file", "line", "column"],
+                  "properties": {
+                    "file": { "type": "string" },
+                    "line": { "type": "integer", "minimum": 1 },
+                    "column": { "type": "integer", "minimum": 1 }
+                  }
+                }
+              ]
+            }
+          }
+        },
+        "members": false,
+        "workspace": false
+      }
+    }
+  }
+}

package/src/workspace/ls.ts

@@ -0,0 +1,254 @@
+/**
+ * `chant workspace ls [dir] [--at <rev>] [--json]` (#2534): list a workspace's
+ * members and example groups from its declaration.
+ *
+ * A member that can't be read is still listed, with a reason code, and the
+ * command still exits 0 (#2524 D15, ws-020). Failing on it is the job of
+ * `chant workspace check`. Only a declaration that can't be read exits 1.
+ *
+ * The `--json` output is part of the read contract, versioned like
+ * `workspace records` and described by `ls.schema.json` beside this file.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import {
+  readDeclaration,
+  readerVersion,
+  resolveGroups,
+  WorkspaceReadError,
+  type Declaration,
+  type ErrorLocation,
+  type Member,
+  type WorkspaceErrorCode,
+} from "./declaration";
+import type { ReasonCode } from "./reason-codes";
+import { loadKindRegistry, probeKind, type KindRegistry } from "./kinds";
+import type { WorkspaceTree } from "./tree";
+import { handToRootChant, locateWorkspace } from "./which-chant";
+
+/** The version of the `ls` output this chant writes. */
+export const LS_CONTRACT_VERSION = 1;
+
+/** `$id` of the JSON Schema for the `--json` output, shipped beside this file. */
+export const LS_OUTPUT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/ls/v1/ls.schema.json";
+
+const USAGE = "chant workspace ls [dir] [--at <rev>] [--json]";
+
+/**
+ * Why one member can't be read. Closed, like the error codes: a new code is a
+ * contract change.
+ */
+export const MEMBER_REASON_CODES = [
+  /** The member's directory does not exist. */
+  "dir-missing",
+  /** No built-in kind or pinned package supplies the member's kind. */
+  "unknown-kind",
+  /** The directory is not what its kind reads, such as a `chant` member with no chant config. */
+  "kind-probe-failed",
+] as const satisfies readonly ReasonCode[];
+export type MemberReasonCode = (typeof MEMBER_REASON_CODES)[number];
+
+/** Why a group lists nothing. */
+export const GROUP_REASON_CODES = [
+  /** No directory the globs match holds a chant project. */
+  "no-matches",
+] as const satisfies readonly ReasonCode[];
+export type GroupReasonCode = (typeof GROUP_REASON_CODES)[number];
+
+export interface LsMember {
+  name: string;
+  dir: string;
+  kind: string;
+  roles: { name: string; path: string | null }[];
+  upstream: string | null;
+  because: string | null;
+  readable: boolean;
+  reason: { code: MemberReasonCode; message: string } | null;
+}
+
+export interface LsGroup {
+  name: string;
+  kind: "examples";
+  glob: string[];
+  matches: string[];
+  skipped: string[];
+  reason: { code: GroupReasonCode; message: string } | null;
+}
+
+export type LsDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      at: string | null;
+      workspace: {
+        name: string;
+        /** The workspace root relative to the git root, `"."` for the git root itself. Absolute outside git. */
+        root: string;
+        file: string;
+        schema: number;
+        minReader: string | null;
+        pins: Declaration["pins"];
+      };
+      members: LsMember[];
+      groups: LsGroup[];
+      summary: { members: number; unreadable: number; groups: number; matches: number };
+    }
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      error: { code: WorkspaceErrorCode; message: string; location: ErrorLocation | null };
+    };
+
+export interface LsQuery {
+  /** Where the walk up to the declaration starts. */
+  cwd: string;
+  at?: string;
+  kinds?: KindRegistry;
+}
+
+/** A member's reason code, or null when its kind can read it. */
+export function memberReason(member: Member, tree: WorkspaceTree, kinds: KindRegistry): LsMember["reason"] {
+  if (tree.stat(member.dir === "." ? "" : member.dir) !== "dir") {
+    return { code: "dir-missing", message: `${member.dir} is not a directory${tree.label}` };
+  }
+  const kind = kinds.get(member.kind);
+  if (!kind) {
+    return { code: "unknown-kind", message: `no built-in kind or pinned package supplies kind ${member.kind}; known kinds: ${kinds.names().join(", ")}` };
+  }
+  if (!probeKind(kind, tree, member.dir === "." ? "" : member.dir)) {
+    return { code: "kind-probe-failed", message: `${member.dir} is not ${kind.description}` };
+  }
+  return null;
+}
+
+/** Find the workspace, read it and build the document `--json` prints. Never throws a {@link WorkspaceReadError}. */
+export function listWorkspace(query: LsQuery): LsDocument {
+  const chant = readerVersion();
+  const head = { $schema: LS_OUTPUT_SCHEMA_ID, contract: LS_CONTRACT_VERSION, chant };
+  try {
+    const located = locateWorkspace(query.cwd, query.at);
+    const { tree, rootOnDisk, at } = located;
+    const declaration = readDeclaration(tree, "", { rootChant: true });
+    // Kinds come from the pinned packages installed in the working tree, also
+    // for --at: they are read as data, never run (#2535).
+    const kinds = query.kinds ?? loadKindRegistry(declaration.pins, rootOnDisk).registry;
+    const groups = resolveGroups(declaration, tree);
+    const members: LsMember[] = declaration.members.map((m) => {
+      const reason = memberReason(m, tree, kinds);
+      return {
+        name: m.name,
+        dir: m.dir,
+        kind: m.kind,
+        roles: m.roles,
+        upstream: m.upstream,
+        because: m.because,
+        readable: reason === null,
+        reason,
+      };
+    });
+    const lsGroups: LsGroup[] = groups.map((g) => ({
+      name: g.group.name,
+      kind: "examples",
+      glob: g.group.globs,
+      matches: g.matches,
+      skipped: g.skipped,
+      reason:
+        g.matches.length === 0
+          ? { code: "no-matches", message: `no directory ${g.group.globs.join(" or ")} matches${tree.label} holds a chant project` }
+          : null,
+    }));
+    return {
+      ...head,
+      at,
+      workspace: {
+        name: declaration.name,
+        root: located.root,
+        file: declaration.file,
+        schema: declaration.schema,
+        minReader: declaration.minReader,
+        pins: declaration.pins,
+      },
+      members,
+      groups: lsGroups,
+      summary: {
+        members: members.length,
+        unreadable: members.filter((m) => !m.readable).length,
+        groups: lsGroups.length,
+        matches: lsGroups.reduce((n, g) => n + g.matches.length, 0),
+      },
+    };
+  } catch (err) {
+    if (!(err instanceof WorkspaceReadError)) throw err;
+    return { ...head, error: { code: err.code, message: err.message, location: err.location ?? null } };
+  }
+}
+
+export async function runWorkspaceLs(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const cwd = resolve(args.extraPositional ?? ".");
+  if (!existsSync(cwd)) {
+    console.error(formatError({ message: `${cwd} does not exist`, hint: USAGE }));
+    return 1;
+  }
+  // The root's chant reads the declaration (ws-021).
+  const handed = await handToRootChant(cwd, args.at);
+  if (handed !== undefined) return handed;
+  const doc = listWorkspace({ cwd, at: args.at });
+  if (args.json) {
+    console.log(JSON.stringify(doc, null, 2));
+  } else if ("error" in doc) {
+    const l = doc.error.location;
+    const where = l ? `${l.file}:${l.line}:${l.column}: ` : "";
+    console.error(formatError({ message: `${doc.error.code}: ${where}${doc.error.message}`, hint: USAGE }));
+  } else {
+    console.log(formatLs(doc));
+  }
+  return "error" in doc ? 1 : 0;
+}
+
+function table(rows: string[][]): string[] {
+  const widths = rows[0].map((_, c) => Math.max(...rows.map((r) => r[c].length)));
+  return rows.map((r) => r.map((cell, c) => (c === r.length - 1 ? cell : cell.padEnd(widths[c]))).join("  ").trimEnd());
+}
+
+function formatLs(doc: Extract<LsDocument, { members: unknown }>): string {
+  const lines: string[] = [];
+  const w = doc.workspace;
+  lines.push(`${w.name}  (${w.root === "." ? w.file : `${w.root}/${w.file}`}${doc.at ? ` at ${doc.at.slice(0, 8)}` : ""})`);
+  if (doc.members.length > 0) {
+    lines.push("");
+    const rows = [["MEMBER", "KIND", "DIR", "ROLES"]];
+    for (const m of doc.members) {
+      rows.push([m.name, m.kind, m.dir, m.roles.map((r) => (r.path ? `${r.name}:${r.path}` : r.name)).join(",")]);
+    }
+    const rendered = table(rows);
+    lines.push(rendered[0]);
+    doc.members.forEach((m, i) => {
+      lines.push(rendered[i + 1]);
+      if (m.reason) lines.push(`  ${m.reason.code}: ${m.reason.message}`);
+    });
+  }
+  if (doc.groups.length > 0) {
+    lines.push("");
+    const rows = [["GROUP", "KIND", "GLOB", "PROJECTS"]];
+    for (const g of doc.groups) rows.push([g.name, g.kind, g.glob.join(" "), String(g.matches.length)]);
+    const rendered = table(rows);
+    lines.push(rendered[0]);
+    doc.groups.forEach((g, i) => {
+      lines.push(rendered[i + 1]);
+      if (g.reason) lines.push(`  ${g.reason.code}: ${g.reason.message}`);
+    });
+  }
+  const s = doc.summary;
+  lines.push("");
+  lines.push(
+    `${s.members} member${s.members === 1 ? "" : "s"}, ${s.unreadable} unreadable; ` +
+      `${s.groups} example group${s.groups === 1 ? "" : "s"} with ${s.matches} project${s.matches === 1 ? "" : "s"}`,
+  );
+  return lines.join("\n");
+}