@zdreamer/forge 0.1.0 → 0.1.2

package/README.md

@@ -1,13 +1,36 @@
 # @zdreamer/forge
 
-Provisional prototype of the Forge workspace application: a policy-loading
-diagnostic, not a server or review UI. Executable: `forge`; public authoring
-types: `@zdreamer/forge/workspace`. Licensed under [MIT](LICENSE).
+Provisional Forge workspace application. The unreleased source supports a
+foreground read-only workspace server, a minimal browser diagnostic and the
+policy-loading diagnostic. Registry release `0.1.1` supplies the diagnostic and policy types; it does not contain the
+server. Executable: `forge`; public authoring types: `@zdreamer/forge/workspace`.
+Licensed under [MIT](LICENSE).
 
 The `0.x` policy contract is provisional. Breaking authoring or semantic changes
 use a minor release with migration notes; exact-pin the application and use its
 own policy types from the same installation. No separate policy-version field or
-compatibility layer is provided. See [release operations](https://github.com/ZDreamer2/forge/blob/master/docs/releasing.md).
+compatibility layer is provided. See [release operations](https://github.com/ZDreamer2/forge/blob/main/docs/releasing.md).
+
+## Source layout
+
+One package and installation own all dependencies. Its directories separate source
+and runtime responsibilities; they are not workspace packages:
+
+```text
+server/src/    CLI, HTTP composition, domain components, public API contract and libs
+ui/src/        reserved standalone React application root (no React/Vite scaffold yet)
+docs/          application architecture and installation guidance
+tools/         tooling/release and installed-consumer checks
+dist/          normal TypeScript output, preserving server/src paths
+```
+
+The server retains its service conventions and local entries at
+`server/docs/forge/`. UI implementation and its browser tooling remain future work;
+the existing vanilla diagnostic is still server-owned. There are no member
+manifests or duplicated dependency declarations. [Architecture](https://github.com/ZDreamer2/forge/blob/main/docs/architecture.md)
+owns source dependencies and build boundaries. The application-owned
+[HTTP API contract](https://github.com/ZDreamer2/forge/blob/main/server/docs/protocol.md)
+specifies wire behavior independently of the currently implemented operations.
 
 ## Develop
 
@@ -20,6 +43,11 @@ corepack pnpm --config.verify-deps-before-run=error run build
 corepack pnpm --config.verify-deps-before-run=error run test:workspace
 ```
 
+For server-only acceptance, run
+`corepack pnpm --config.verify-deps-before-run=error run check:server` from this
+root. It includes server/contract typechecks, server-scoped Biome checks,
+architectural dependency rules and server tests.
+
 The independent installation uses published `@zdreamer/forge-ts-service@0.1.1`
 presets, their exact-pinned tool peers, the seven-day third-party release-age
 floor, and explicit SWC script permission. `.cache/pnpm` is the portable default;
@@ -27,14 +55,120 @@ a hosting checkout can override the store during installation.
 
 `test:workspace` checks public types and the installed executable through an
 isolated tarball consumer, without publishing or running install scripts. An
-optional `workspace.ts` argument also checks a consuming project's policy.
+optional `workspace.ts` argument also checks a consuming project's policy. Run
+aggregate commands at the repository root: the gate delegates service-local checks
+to `server/`, including its public API contract's browser-safety checks, and verifies
+cross-runtime boundaries at the root.
+Build is a clean followed by ordinary TypeScript compilation, without output
+flattening or import rewriting. Root `bin` and `exports` select the emitted paths;
+use the command/public export instead of depending on physical dist paths.
+
+## Run the source server
+
+After building, run from this repository:
+
+```sh
+node dist/server/src/main.js serve --workspace /absolute/path/to/checkout
+```
+
+The CLI form is `forge serve --workspace <path>` once a server-capable release
+is installed. Relative workspace paths resolve against the invocation directory;
+the selected directory is canonicalized as the authoritative checkout.
+
+Startup loads exactly `<guidance-folder>/workspace.ts`. The default folder is
+`docs/forge/workspace` inside the selected checkout. A nonempty process
+`ZD_AI_FORGE_WORKSPACE_GUIDE` selects a different folder, relative to that checkout
+or absolute; `.env` cannot set this override. Invalid explicit choices fail
+without ancestor search or fallback. The standalone server requires the trusted
+TypeScript module; it does not consume the Python workflow's
+`on-codebase-selection.md` or concrete/type registrations in `forge-workspace.yaml`.
+Its policy membership rules are not yet aligned with Python's concrete-first
+routing. External trusted guidance folders are allowed.
+
+Set `ZD_AI_FORGE_PORT` in the process environment or selected checkout's `.env`.
+A nonempty process value takes precedence, including invalid values; an empty
+process value falls back to `.env`. Ports use one to five ASCII decimal digits
+and range from 1024 through 65535. There is no default, allocation or occupied-port
+fallback. The narrow `.env` syntax supports whole-line comments, optional
+`export`, whitespace and surrounding quotes; last assignment wins and malformed
+lines are ignored. It performs no interpolation, multiline or escape expansion;
+only the port setting is imported. A missing `.env` is allowed, while unreadable
+or invalid-encoding files fail startup.
+
+After listener readiness, the foreground process prints its package version,
+JSON-quoted executable and authoritative workspace paths, then
+`http://127.0.0.1:<port>` on its own line. It prints no environment values.
+The `inspect-workspace` diagnostic retains its JSON-only stdout contract.
+Open that address to see workspace/repository identity and current changed files,
+including Git-reported rename sources and concrete
+codebase memberships. Workspace names, paths and guidance are displayed literally
+as text. The browser title uses `🛠️ <workspace name>` from server identity;
+it starts as `Forge` and returns to `Forge` when the identity request fails.
+The page shows loading, empty and error states; Refresh retries failed requests and clears the
+previous change list while loading. Successful workspace identity is retained
+when a request fails. Refresh reads current changes but does not reload startup
+policy or repository participation. There is no polling.
+
+`GET /api/workspace` returns the workspace root, resolved display name and declared
+available/missing repositories in declaration order. Invalid existing repositories, Git/access
+failures and policy/configuration errors refuse startup. Requests require that
+exact Host and, when present, Origin; CLI requests may omit Origin. Restart to
+reload configuration, policy and repository identity. Stop with SIGINT or
+SIGTERM; shutdown closes the listener and releases the port.
+
+`GET /api/changes` returns
+`{ codebases: { id: { guidance: "path" } }, changes: [...] }`. Changes carry repo,
+workspace-relative path, added/modified/deleted/renamed kind, optional rename
+`from` and unique codebase ID arrays. Definitions occur once per response;
+conflicting guidance for one ID fails collection. No binary/line counts.
+
+Comparison uses one bulk HEAD/working `diff --raw --numstat -z` and non-ignored untracked listing,
+with targeted normalized hash/mode reconciliation for recreated deletion/rename
+sources. Index refresh is disabled; numstat presence removes raw stat noise while
+mode/type changes, zero-count changes and binaries remain. Counts stay internal.
+Identical staged reversals disappear. Git owns attributes, filters and
+index flags; hidden flag edits can remain hidden, and ignored recreations absent
+from the untracked list remain deletions. Unstaged moves stay deletion/addition.
+Unborn HEAD is supported; conflicts fail even with no diff. This is practical Git
+comparison, not exhaustive physical equivalence or a replacement for dirt detection.
+
+The observed command baseline is Git 2.34.1. Complete local repositories are
+supported; partial/promisor repositories fail before object-demanding comparison
+to prevent silent lazy fetch. Normal trusted clean/process filters are allowed;
+external diff/textconv, optional writes, fsmonitor and hooks are disabled. Ambient
+Git repository/index/worktree overrides do not select another checkout. Server
+commands do not stage/commit/write indexes, refs or objects. Trusted policy and
+filters can execute code with side effects; this is not an effects sandbox.
+
+Missing-at-startup repositories remain excluded; loss of an available repository,
+Git failures or invalid/throwing routing results fail the whole request. Paths
+stay inside the workspace even when its Git root extends above it. Declared
+nested repositories are distinct; undeclared clones and Git internals are excluded.
+Results are live observations, without atomic cross-repository snapshots.
+Overlapping requests share one active collection, with no result cache. A
+30-second collection deadline bounds waiting; shutdown aborts and reaps active
+Git children before completion. The browser allows 35 seconds per request, then restores retry.
+
+For a direct check while the server runs, replace the example address with the
+address printed by the server:
+
+```sh
+FORGE_ADDRESS=http://127.0.0.1:12345
+curl "$FORGE_ADDRESS/api/workspace"
+curl "$FORGE_ADDRESS/api/changes"
+```
+
+The server and browser page are read-only: no staging, commits, diff rendering,
+file browsing or agent interaction. Registry `0.1.1` remains the diagnostic-only
+release; source and installed-tarball verification do not constitute publication
+or registry adoption.
 
 ## Workspace authoring contract (provisional)
 
 Projects can exact-pin Forge as a local development dependency:
 
 ```sh
-pnpm add --save-dev --save-exact @zdreamer/forge@0.1.0
+pnpm add --save-dev --save-exact @zdreamer/forge@0.1.1
 ```
 
 ```ts
@@ -46,6 +180,24 @@ export default {
 } satisfies WorkspacePolicy;
 ```
 
+The unreleased source also accepts optional `displayName` policy metadata. An
+explicit value must be a nonempty string and is preserved exactly, without
+trimming or HTML interpretation. The server resolves an omitted name to the
+canonical workspace root's basename, or the root itself if it has no basename,
+and returns it as `workspace.name` in identity. Restart to reload the name.
+Registry `0.1.1` does not declare this field in its authoring types. To retain
+metadata while typechecking against that exact pin, use a structurally checked
+variable:
+
+```ts
+const policy = {
+  displayName: 'Example workspace',
+  repositories: [{ path: '.' }],
+  codebasesForChange: () => [],
+};
+export default policy satisfies WorkspacePolicy;
+```
+
 Module lookup follows the workspace file's ancestors, not the executable's
 installation. A global executable alone does not supply editor/typechecker
 resolution. Keep the dependency in an installation above the workspace module;
@@ -62,10 +214,11 @@ Repository IDs use `.` for the main repo and normalized workspace-relative POSIX
 paths for nested repos. Change paths are workspace-relative; legacy CLI changes
 can include `../` paths when the main Git root lies above the workspace.
 `codebasesForChange` resolves membership lexically, without requiring files to
-exist, and includes both rename/copy sides. Several concrete codebases can share
+exist, and includes both rename sides. Several concrete codebases can share
 guidance; membership does not imply verification.
 
 Policy modules are trusted executable code, not sandboxed; installation does not
-load them. Types do not validate callback results at runtime. See
-[architecture](https://github.com/ZDreamer2/forge/blob/master/docs/architecture.md) for loading limits and repository resolution,
+load them. The changes collector validates callback results at runtime; the diagnostic
+uses the authored types without that validation. See
+[architecture](https://github.com/ZDreamer2/forge/blob/main/docs/architecture.md) for loading limits and repository resolution,
 which the diagnostic does not invoke.

package/dist/server/src/app/collection.d.ts

@@ -0,0 +1,10 @@
+type Deps<T> = {
+    collect: (signal: AbortSignal) => Promise<T>;
+    timeoutMs?: number;
+};
+/** One live operation shared by callers; settled results are never cached. */
+export declare function createCollection<T>({ collect, timeoutMs }: Deps<T>): {
+    collect(): Promise<T>;
+    close(): Promise<void>;
+};
+export {};

package/dist/server/src/app/collection.js

@@ -0,0 +1,29 @@
+/** One live operation shared by callers; settled results are never cached. */
+export function createCollection({ collect, timeoutMs = 30_000 }) {
+    let accepting = true;
+    let active;
+    return {
+        collect() {
+            if (!accepting)
+                return Promise.reject(new Error("Forge is shutting down"));
+            if (active)
+                return active.promise;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error("Workspace collection timed out")), timeoutMs);
+            const promise = Promise.resolve()
+                .then(() => collect(controller.signal))
+                .finally(() => {
+                clearTimeout(timer);
+                active = undefined;
+            });
+            active = { controller, promise };
+            return promise;
+        },
+        async close() {
+            accepting = false;
+            const pending = active;
+            pending?.controller.abort(new Error("Forge is shutting down"));
+            await pending?.promise.catch(() => { });
+        },
+    };
+}

package/dist/server/src/app/config.d.ts

@@ -0,0 +1,12 @@
+export interface Config {
+    readonly root: string;
+    readonly policyPath: string;
+    readonly port: number;
+}
+interface ConfigInput {
+    workspace: string;
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+}
+export declare function loadConfig({ workspace, cwd, env }: ConfigInput): Promise<Readonly<Config>>;
+export {};

package/dist/server/src/app/config.js

@@ -0,0 +1,52 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+export async function loadConfig({ workspace, cwd, env }) {
+    const guidance = env.ZD_AI_FORGE_WORKSPACE_GUIDE || "docs/forge/workspace";
+    const processPort = env.ZD_AI_FORGE_PORT;
+    const selected = resolve(cwd, workspace);
+    if (!(await stat(selected)).isDirectory()) {
+        throw new Error("Workspace must be a directory");
+    }
+    const root = await realpath(selected);
+    const policyPath = join(resolve(root, guidance), "workspace.ts");
+    if (!(await stat(policyPath)).isFile()) {
+        throw new Error("Workspace policy must be a workspace.ts file in the selected guidance folder");
+    }
+    const dotenvPort = await readDotenvPort(join(root, ".env"));
+    const value = processPort || dotenvPort || "";
+    if (!/^[0-9]{1,5}$/.test(value) || Number(value) < 1024 || Number(value) > 65535) {
+        throw new Error("ZD_AI_FORGE_PORT must be an ASCII decimal TCP port from 1024 through 65535");
+    }
+    return Object.freeze({ root, policyPath, port: Number(value) });
+}
+async function readDotenvPort(path) {
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(await readFile(path));
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw new Error("Cannot read the workspace .env file as UTF-8");
+    }
+    let port;
+    // Match the workspace's narrow dotenv syntax: no interpolation, escapes,
+    // inline comments or multiline values; the last assignment wins.
+    // biome-ignore lint/suspicious/noControlCharactersInRegex: Python splitlines recognizes these separators.
+    for (const raw of text.split(/\r\n|[\n\r\v\f\x1c-\x1e\u0085\u2028\u2029]/)) {
+        let line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("export "))
+            line = line.slice(7).trimStart();
+        const separator = line.indexOf("=");
+        if (separator < 0 || line.slice(0, separator).trim() !== "ZD_AI_FORGE_PORT")
+            continue;
+        let value = line.slice(separator + 1).trim();
+        if (value.length >= 2 && (value[0] === '"' || value[0] === "'") && value.at(-1) === value[0]) {
+            value = value.slice(1, -1);
+        }
+        port = value;
+    }
+    return port;
+}

package/dist/server/src/app/http.d.ts

@@ -0,0 +1,13 @@
+import { Hono } from "hono";
+import type { CollectedWorkspaceChanges } from "../components/workspace-changes/index.ts";
+import type { RepositoryResolution } from "../components/workspace-policy/index.ts";
+type Deps = {
+    root: string;
+    name: string;
+    repositories: readonly RepositoryResolution[];
+    port: number;
+    collectChanges: () => Promise<CollectedWorkspaceChanges>;
+    reportError?: (error: Error) => void;
+};
+export declare function createHttpApp({ root, name, repositories, port, collectChanges, reportError }: Deps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export {};

package/dist/server/src/app/http.js

@@ -0,0 +1,19 @@
+import { Hono } from "hono";
+import { createDiagnosticRoutes } from "../components/diagnostic-ui/index.js";
+import { AccessRejectedError, createRequestGuard } from "../lib/loopback-access/index.js";
+import { apiError } from "./wire.js";
+import { createWorkspaceRoutes } from "./workspace-routes.js";
+export function createHttpApp({ root, name, repositories, port, collectChanges, reportError }) {
+    const app = new Hono();
+    app.onError((error, context) => {
+        if (error instanceof AccessRejectedError)
+            return context.json(apiError("forbidden"), 403);
+        reportError?.(error);
+        return context.json(apiError("internal_error"), 500);
+    });
+    app.use("*", createRequestGuard({ port }));
+    app.route("/", createDiagnosticRoutes());
+    app.route("/api", createWorkspaceRoutes({ root, name, repositories, collectChanges }));
+    app.notFound((context) => context.json(apiError("not_found"), 404));
+    return app;
+}

package/dist/server/src/app/listener.d.ts

@@ -0,0 +1,9 @@
+type Deps = {
+    fetch: (request: Request) => Response | Promise<Response>;
+    port: number;
+};
+export declare function createListener({ fetch, port }: Deps): Promise<{
+    address: string;
+    close(): Promise<void>;
+}>;
+export {};

package/dist/server/src/app/listener.js

@@ -0,0 +1,61 @@
+import { createServer } from "node:http";
+import { getRequestListener, RequestError } from "@hono/node-server";
+import { apiError } from "./wire.js";
+export async function createListener({ fetch, port }) {
+    const server = createServer(getRequestListener(fetch, {
+        overrideGlobalObjects: false,
+        errorHandler: (error) => Response.json(apiError(error instanceof RequestError ? "forbidden" : "internal_error"), {
+            status: error instanceof RequestError ? 403 : 500,
+        }),
+    }));
+    const sockets = new Set();
+    const onConnection = (socket) => {
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+    };
+    server.on("connection", onConnection);
+    try {
+        await new Promise((resolve, reject) => {
+            const onError = (error) => {
+                server.off("listening", onListening);
+                reject(error);
+            };
+            const onListening = () => {
+                server.off("error", onError);
+                resolve();
+            };
+            server.once("error", onError);
+            server.once("listening", onListening);
+            server.listen(port, "127.0.0.1");
+        });
+    }
+    catch (error) {
+        server.off("connection", onConnection);
+        throw error;
+    }
+    const address = server.address();
+    if (!address || typeof address === "string")
+        throw new Error("Missing listener address");
+    let closing;
+    return {
+        address: `http://127.0.0.1:${address.port}`,
+        close() {
+            closing ??= new Promise((resolve, reject) => {
+                // Bound draining so an incomplete request cannot keep foreground shutdown alive.
+                const timer = setTimeout(() => {
+                    for (const socket of sockets)
+                        socket.destroy();
+                }, 500);
+                server.close((error) => {
+                    clearTimeout(timer);
+                    server.off("connection", onConnection);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve();
+                });
+            });
+            return closing;
+        },
+    };
+}

package/dist/server/src/app/startup.d.ts

@@ -0,0 +1,16 @@
+type Options = {
+    workspace: string;
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+};
+export declare function start(options: Options): Promise<{
+    address: string;
+    close: () => Promise<void>;
+    snapshot: Readonly<{
+        root: string;
+        name: string;
+        policy: import("../components/workspace-policy/index.ts").WorkspacePolicy;
+        repositories: readonly import("../components/workspace-policy/index.ts").RepositoryResolution[];
+    }>;
+}>;
+export {};

package/dist/server/src/app/startup.js

@@ -0,0 +1,60 @@
+import { basename } from "node:path";
+import { createWorkspaceChanges } from "../components/workspace-changes/index.js";
+import { loadWorkspacePolicy, resolveRepositories } from "../components/workspace-policy/index.js";
+import { createGitProcess } from "../lib/git/index.js";
+import { createCollection } from "./collection.js";
+import { loadConfig } from "./config.js";
+import { createHttpApp } from "./http.js";
+import { createListener } from "./listener.js";
+export async function start(options) {
+    const config = await loadConfig(options);
+    const policy = await loadWorkspacePolicy(config.policyPath);
+    const git = createGitProcess(options.env);
+    const repositories = await resolveRepositories(config.root, policy.repositories, git);
+    const name = policy.displayName ?? (basename(config.root) || config.root);
+    const snapshot = Object.freeze({ root: config.root, name, policy, repositories });
+    const changes = createWorkspaceChanges({
+        root: config.root,
+        repositories,
+        codebasesForChange: (change) => policy.codebasesForChange(change),
+        git,
+    });
+    const collection = createCollection({ collect: (signal) => changes.collect(signal) });
+    const app = createHttpApp({
+        ...snapshot,
+        collectChanges: collection.collect,
+        port: config.port,
+        reportError: (error) => {
+            const causes = [];
+            let current = error;
+            while (current instanceof Error && causes.length < 3) {
+                causes.push(current.message);
+                current = current.cause;
+            }
+            const message = causes
+                .join(": ")
+                .replace(/\p{Cc}/gu, " ")
+                .slice(0, 1600);
+            console.error(`Forge workspace request failed: ${message}`);
+        },
+    });
+    const listener = await createListener({ fetch: app.fetch, port: config.port });
+    let disposal;
+    function close() {
+        if (disposal === undefined) {
+            process.off("SIGINT", terminate);
+            process.off("SIGTERM", terminate);
+            disposal = Promise.all([collection.close(), listener.close()]).then(() => { });
+        }
+        return disposal;
+    }
+    function terminate() {
+        void close().catch(() => {
+            console.error("Forge shutdown failed");
+            process.exitCode = 1;
+        });
+    }
+    process.on("SIGINT", terminate);
+    process.on("SIGTERM", terminate);
+    return { address: listener.address, close, snapshot };
+}

package/dist/server/src/app/wire.d.ts

@@ -0,0 +1,11 @@
+import type { ApiErrorCode, WorkspaceChanges, WorkspaceIdentity } from "../components/api-contract/index.ts";
+import type { CollectedWorkspaceChanges } from "../components/workspace-changes/index.ts";
+import type { RepositoryResolution } from "../components/workspace-policy/index.ts";
+export declare function apiError(code: ApiErrorCode): {
+    error: {
+        code: ApiErrorCode;
+        message: string;
+    };
+};
+export declare function workspaceIdentity(root: string, name: string, repositories: readonly RepositoryResolution[]): WorkspaceIdentity;
+export declare function workspaceChanges(result: CollectedWorkspaceChanges): WorkspaceChanges;

package/dist/server/src/app/wire.js

@@ -0,0 +1,29 @@
+export function apiError(code) {
+    const messages = {
+        forbidden: "Request forbidden",
+        not_found: "Not found",
+        method_not_allowed: "Method not allowed",
+        internal_error: "Internal server error",
+    };
+    return { error: { code, message: messages[code] } };
+}
+export function workspaceIdentity(root, name, repositories) {
+    return {
+        workspace: { root, name },
+        repositories: repositories.map((repository) => repository.status === "available"
+            ? { path: repository.path, status: "available", gitRoot: repository.gitRoot }
+            : { path: repository.path, status: "missing" }),
+    };
+}
+export function workspaceChanges(result) {
+    return {
+        codebases: Object.fromEntries(Object.entries(result.codebases).map(([id, definition]) => [id, { guidance: definition.guidance }])),
+        changes: result.changes.map((change) => ({
+            repo: change.repo,
+            path: change.path,
+            kind: change.kind,
+            ...(change.kind === "renamed" && change.from !== undefined ? { from: change.from } : {}),
+            codebases: [...change.codebases],
+        })),
+    };
+}

package/dist/server/src/app/workspace-routes.d.ts

@@ -0,0 +1,11 @@
+import { Hono } from "hono";
+import type { CollectedWorkspaceChanges } from "../components/workspace-changes/index.ts";
+import type { RepositoryResolution } from "../components/workspace-policy/index.ts";
+type Deps = {
+    root: string;
+    name: string;
+    repositories: readonly RepositoryResolution[];
+    collectChanges: () => Promise<CollectedWorkspaceChanges>;
+};
+export declare function createWorkspaceRoutes({ root, name, repositories, collectChanges }: Deps): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export {};

package/dist/server/src/app/workspace-routes.js

@@ -0,0 +1,15 @@
+import { Hono } from "hono";
+import { apiError, workspaceChanges, workspaceIdentity } from "./wire.js";
+export function createWorkspaceRoutes({ root, name, repositories, collectChanges }) {
+    const identity = workspaceIdentity(root, name, repositories);
+    const routes = new Hono();
+    routes.get("/workspace", (context) => context.json(identity));
+    routes.get("/changes", async (context) => context.json(workspaceChanges(await collectChanges())));
+    for (const path of ["/workspace", "/changes"]) {
+        routes.all(path, (context) => {
+            context.header("Allow", "GET, HEAD");
+            return context.json(apiError("method_not_allowed"), 405);
+        });
+    }
+    return routes;
+}

package/dist/server/src/components/api-contract/index.d.ts

@@ -0,0 +1 @@
+export type { ApiErrorCode, WorkspaceChanges, WorkspaceIdentity } from "./internal/types.ts";

package/dist/server/src/components/api-contract/internal/types.d.ts

@@ -0,0 +1,27 @@
+export type WorkspaceIdentity = {
+    workspace: {
+        root: string;
+        name: string;
+    };
+    repositories: ({
+        path: string;
+        status: "available";
+        gitRoot: string;
+    } | {
+        path: string;
+        status: "missing";
+    })[];
+};
+export type ApiErrorCode = "forbidden" | "not_found" | "method_not_allowed" | "internal_error";
+export type WorkspaceChanges = {
+    codebases: Record<string, {
+        guidance: string;
+    }>;
+    changes: {
+        repo: string;
+        path: string;
+        kind: "added" | "modified" | "deleted" | "renamed";
+        from?: string;
+        codebases: string[];
+    }[];
+};

package/dist/server/src/components/diagnostic-ui/index.d.ts

@@ -0,0 +1 @@
+export { createDiagnosticRoutes } from "./internal/routes.ts";

package/dist/server/src/components/diagnostic-ui/index.js

@@ -0,0 +1 @@
+export { createDiagnosticRoutes } from "./internal/routes.js";

package/dist/server/src/components/diagnostic-ui/internal/page.d.ts

@@ -0,0 +1 @@
+export declare const page = "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<link rel=\"icon\" href=\"data:,\">\n<title>Forge</title>\n<style>\nbody { font: 16px system-ui, sans-serif; margin: 2rem auto; padding: 0 1rem; max-width: 75rem; color: #202830; background: #fafbfc; }\nbutton { font: inherit; padding: .5rem 1rem; cursor: pointer; }\nbutton:disabled { cursor: wait; }\nli { margin: .75rem 0; overflow-wrap: anywhere; }\n.path { font-family: ui-monospace, monospace; }\n.error { color: #a02020; }\nsection { border-top: 1px solid #ccd3da; margin-top: 1.5rem; }\n</style>\n</head>\n<body>\n<h1>Forge workspace</h1>\n<p>Read-only workspace diagnostic. Refresh reads current changes. Restart the server to reload policy and repository participation.</p>\n<button id=\"refresh\" type=\"button\">Refresh</button>\n<p id=\"status\" role=\"status\" aria-live=\"polite\">Loading\u2026</p>\n<section aria-labelledby=\"identity-heading\">\n<h2 id=\"identity-heading\">Workspace and repositories</h2>\n<p id=\"identity-error\" class=\"error\" role=\"alert\"></p>\n<div id=\"identity\"></div>\n</section>\n<section aria-labelledby=\"changes-heading\">\n<h2 id=\"changes-heading\">Current changes</h2>\n<p id=\"changes-error\" class=\"error\" role=\"alert\"></p>\n<div id=\"changes\"></div>\n</section>\n<script>\n\"use strict\";\nconst refreshButton = document.getElementById(\"refresh\");\nconst status = document.getElementById(\"status\");\nconst identity = document.getElementById(\"identity\");\nconst changes = document.getElementById(\"changes\");\nconst identityError = document.getElementById(\"identity-error\");\nconst changesError = document.getElementById(\"changes-error\");\nfunction textElement(tag, text, className) {\n  const element = document.createElement(tag);\n  element.textContent = text;\n  if (className) element.className = className;\n  return element;\n}\nasync function request(path) {\n  const controller = new AbortController();\n  let timer;\n  try {\n    return await Promise.race([\n      (async () => {\n        const response = await fetch(path, { cache: \"no-store\", signal: controller.signal });\n        if (!response.ok) throw new Error(\"Request failed (HTTP \" + response.status + \")\");\n        return response.json();\n      })(),\n      new Promise((_, reject) => {\n        // Allow the server's 30-second collection deadline to return its response first.\n        timer = setTimeout(() => {\n          reject(new Error(\"Request timed out\"));\n          controller.abort();\n        }, 35000);\n      })\n    ]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\nfunction showIdentity(data) {\n  document.title = \"\uD83D\uDEE0\uFE0F \" + data.workspace.name;\n  const root = textElement(\"p\", data.workspace.root, \"path\");\n  const list = document.createElement(\"ul\");\n  for (const repo of data.repositories) {\n    list.append(textElement(\"li\", repo.path + \" \u2014 \" + repo.status + (repo.gitRoot ? \" \u2014 \" + repo.gitRoot : \"\"), \"path\"));\n  }\n  identity.replaceChildren(root, list);\n}\nfunction showChanges(data) {\n  if (data.changes.length === 0) {\n    changes.replaceChildren(textElement(\"p\", \"No uncommitted changes.\"));\n    return;\n  }\n  const list = document.createElement(\"ul\");\n  for (const change of data.changes) {\n    const item = document.createElement(\"li\");\n    item.append(textElement(\"p\", change.repo + \" \u00B7 \" + change.path + \" \u2014 \" + change.kind, \"path\"));\n    if (change.from !== undefined) item.append(textElement(\"p\", \"From: \" + change.from, \"path\"));\n    const memberships = document.createElement(\"ul\");\n    for (const id of change.codebases) {\n      memberships.append(textElement(\"li\", id + \" \u2014 \" + data.codebases[id].guidance, \"path\"));\n    }\n    item.append(change.codebases.length ? memberships : textElement(\"p\", \"No codebase membership.\"));\n    list.append(item);\n  }\n  changes.replaceChildren(list);\n}\nasync function refresh() {\n  if (refreshButton.disabled) return;\n  refreshButton.disabled = true;\n  status.textContent = \"Loading\u2026\";\n  changes.replaceChildren();\n  identityError.textContent = \"\";\n  changesError.textContent = \"\";\n  try {\n    async function load(path, show, region, label) {\n      try {\n        show(await request(path));\n        return true;\n      } catch (error) {\n        if (path === \"/api/workspace\") document.title = \"Forge\";\n        region.textContent = label + \": \" + error.message + \". Use Refresh to retry.\";\n        status.textContent = \"Refresh failed. Use Refresh to retry.\";\n        return false;\n      }\n    }\n    const results = await Promise.all([\n      load(\"/api/workspace\", showIdentity, identityError, \"Workspace\"),\n      load(\"/api/changes\", showChanges, changesError, \"Changes\")\n    ]);\n    status.textContent = results.every(Boolean) ? \"Up to date.\" : \"Refresh failed. Use Refresh to retry.\";\n  } finally {\n    refreshButton.disabled = false;\n  }\n}\nrefreshButton.addEventListener(\"click\", refresh);\nrefresh();\n</script>\n</body>\n</html>";