@zdreamer/forge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZDreamer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @zdreamer/forge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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).
+
+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).
+
+## Develop
+
+Use Node 24.21.0 (`.nvmrc`) and Corepack pnpm 11.15.1:
+
+```sh
+corepack pnpm install --frozen-lockfile
+corepack pnpm --config.verify-deps-before-run=error run check
+corepack pnpm --config.verify-deps-before-run=error run build
+corepack pnpm --config.verify-deps-before-run=error run test:workspace
+```
+
+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;
+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.
+
+## 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
+```
+
+```ts
+import type { WorkspacePolicy } from '@zdreamer/forge/workspace';
+
+export default {
+  repositories: [{ path: '.' }, { path: 'tools/optional-checkout' }],
+  codebasesForChange: () => [{ id: 'application', guidance: 'docs/code' }],
+} 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;
+an isolated installation beside that module is also sufficient.
+
+The current diagnostic command loads a selected trusted module explicitly:
+
+```sh
+forge inspect-workspace /absolute/path/workspace.ts . src/example.ts
+# Optional last argument: previous path of a rename.
+```
+
+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
+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,
+which the diagnostic does not invoke.

package/dist/app/inspect.d.ts

@@ -0,0 +1,5 @@
+/** A lexical policy diagnostic; repository probes are explicit startup/reload work. */
+export declare function inspect(modulePath: string, repo: string, path: string, from?: string): Promise<{
+    included: boolean;
+    codebases: readonly import("../components/workspace-policy/index.ts").CodebaseContext[];
+}>;

package/dist/app/inspect.js

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { loadWorkspacePolicy } from "../components/workspace-policy/index.js";
+/** A lexical policy diagnostic; repository probes are explicit startup/reload work. */
+export async function inspect(modulePath, repo, path, from) {
+    const policy = await loadWorkspacePolicy(resolve(modulePath));
+    return {
+        included: policy.repositories.some((repository) => repository.path === repo),
+        codebases: policy.codebasesForChange({
+            repo,
+            path,
+            kind: from === undefined ? "modified" : "renamed",
+            ...(from === undefined ? {} : { from }),
+        }),
+    };
+}

package/dist/components/workspace-policy/index.d.ts

@@ -0,0 +1,3 @@
+export { loadWorkspacePolicy } from "./internal/load.ts";
+export { resolveRepositories } from "./internal/repositories.ts";
+export type { CodebaseContext, RepositoryDeclaration, WorkspaceChange, WorkspacePolicy, } from "./internal/types.ts";

package/dist/components/workspace-policy/index.js

@@ -0,0 +1,2 @@
+export { loadWorkspacePolicy } from "./internal/load.js";
+export { resolveRepositories } from "./internal/repositories.js";

package/dist/components/workspace-policy/internal/load.d.ts

@@ -0,0 +1,3 @@
+import type { WorkspacePolicy } from "./types.ts";
+/** Imports execute trusted workspace code; this is not a sandbox or hot loader. */
+export declare function loadWorkspacePolicy(absolutePath: string): Promise<WorkspacePolicy>;

package/dist/components/workspace-policy/internal/load.js

@@ -0,0 +1,35 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { pathToFileURL } from "node:url";
+import { validRepositoryPath } from "./repositories.js";
+/** Imports execute trusted workspace code; this is not a sandbox or hot loader. */
+export async function loadWorkspacePolicy(absolutePath) {
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(absolutePath).href));
+    const policy = module.default;
+    if (typeof policy !== "object" ||
+        policy === null ||
+        !("repositories" in policy) ||
+        !Array.isArray(policy.repositories) ||
+        !("codebasesForChange" in policy) ||
+        typeof policy.codebasesForChange !== "function") {
+        throw new TypeError("Workspace module must default-export a WorkspacePolicy");
+    }
+    const paths = new Set();
+    for (const repository of policy.repositories) {
+        if (typeof repository !== "object" ||
+            repository === null ||
+            typeof repository.path !== "string" ||
+            !validRepositoryPath(repository.path) ||
+            paths.has(repository.path)) {
+            throw new TypeError("Repository declarations need unique normalized workspace-relative paths");
+        }
+        paths.add(repository.path);
+    }
+    return policy;
+}

package/dist/components/workspace-policy/internal/repositories.d.ts

@@ -0,0 +1,12 @@
+import type { RepositoryDeclaration } from "./types.ts";
+export declare function validRepositoryPath(path: string): boolean;
+export type RepositoryResolution = {
+    readonly path: string;
+    readonly status: "available";
+    readonly gitRoot: string;
+} | {
+    readonly path: string;
+    readonly status: "missing";
+};
+/** Explicit startup/reload probe, never a recursive scan or change-list poll. */
+export declare function resolveRepositories(workspaceRoot: string, declarations: readonly RepositoryDeclaration[]): Promise<readonly RepositoryResolution[]>;

package/dist/components/workspace-policy/internal/repositories.js

@@ -0,0 +1,52 @@
+import { execFile } from "node:child_process";
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { promisify } from "node:util";
+const execute = promisify(execFile);
+export function validRepositoryPath(path) {
+    return (path === "." ||
+        (path.length > 0 &&
+            !path.includes("\\") &&
+            !path.includes(":") &&
+            !path.includes("\0") &&
+            path.split("/").every((part) => part !== "" && part !== "." && part !== "..")));
+}
+/** Explicit startup/reload probe, never a recursive scan or change-list poll. */
+export async function resolveRepositories(workspaceRoot, declarations) {
+    const root = await realpath(workspaceRoot);
+    const results = [];
+    const seen = new Set();
+    for (const declaration of declarations) {
+        const path = declaration.path;
+        if (!validRepositoryPath(path) || seen.has(path)) {
+            throw new TypeError("Repository declarations need unique normalized workspace-relative paths");
+        }
+        seen.add(path);
+        const location = resolve(root, path);
+        try {
+            if (!(await stat(location)).isDirectory()) {
+                throw new Error(`Declared repository is not a directory: ${path}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                results.push({ path, status: "missing" });
+                continue;
+            }
+            throw error;
+        }
+        const directory = await realpath(location);
+        const within = relative(root, directory);
+        if (isAbsolute(within) || within === ".." || within.startsWith(`..${sep}`)) {
+            throw new Error(`Declared repository escapes workspace root: ${path}`);
+        }
+        const { stdout } = await execute("git", ["-C", directory, "rev-parse", "--show-toplevel"]);
+        const gitRoot = await realpath(stdout.trim());
+        // '.' intentionally permits a Git root above the selected workspace.
+        if (path !== "." && gitRoot !== directory) {
+            throw new Error(`Declared nested repository resolves to another Git root: ${path}`);
+        }
+        results.push({ path, status: "available", gitRoot });
+    }
+    return results;
+}

package/dist/components/workspace-policy/internal/types.d.ts

@@ -0,0 +1,25 @@
+/** Paths use '/' and are workspace-relative; '.' identifies the main repository. */
+export interface RepositoryDeclaration {
+    readonly path: string;
+}
+export interface WorkspaceChange {
+    readonly repo: string;
+    readonly path: string;
+    readonly kind: "added" | "modified" | "deleted" | "renamed" | "copied" | "type_changed";
+    readonly from?: string;
+}
+/** Identity is concrete; several codebases may share the same guidance folder. */
+export interface CodebaseContext {
+    readonly id: string;
+    readonly guidance: string;
+}
+/**
+ * Trusted project code, called explicitly after loading. Forge probes only
+ * declared repositories; missing locations are skipped, not configuration errors.
+ * Routing is synchronous, side-effect-free and must handle absent
+ * files lexically. Rename/copy membership includes both old and new paths.
+ */
+export interface WorkspacePolicy {
+    readonly repositories: readonly RepositoryDeclaration[];
+    codebasesForChange(change: WorkspaceChange): readonly CodebaseContext[];
+}

package/dist/components/workspace-policy/internal/types.js

@@ -0,0 +1 @@
+export {};

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { inspect } from "./app/inspect.js";
+const [command, modulePath, repo, path, from, ...extra] = process.argv.slice(2);
+if (command === "--help" || command === undefined) {
+    console.log("forge inspect-workspace <workspace.ts> <repository> <path> [previous-path]");
+}
+else if (command !== "inspect-workspace" ||
+    modulePath === undefined ||
+    repo === undefined ||
+    path === undefined ||
+    extra.length > 0) {
+    console.error("Usage: forge inspect-workspace <workspace.ts> <repository> <path> [previous-path]");
+    process.exitCode = 1;
+}
+else {
+    try {
+        console.log(JSON.stringify(await inspect(modulePath, repo, path, from)));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/dist/workspace.d.ts

@@ -0,0 +1 @@
+export type { CodebaseContext, RepositoryDeclaration, WorkspaceChange, WorkspacePolicy, } from "./components/workspace-policy/index.ts";

package/dist/workspace.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@zdreamer/forge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zdreamer/forge",
+	"version": "0.1.0",
+	"description": "Forge workspace application and typed workspace policy contract",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ZDreamer2/forge.git"
+	},
+	"homepage": "https://github.com/ZDreamer2/forge#readme",
+	"bugs": "https://github.com/ZDreamer2/forge/issues",
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist/"
+	],
+	"bin": {
+		"forge": "./dist/main.js"
+	},
+	"exports": {
+		"./workspace": {
+			"types": "./dist/workspace.d.ts",
+			"default": "./dist/workspace.js"
+		}
+	},
+	"engines": {
+		"node": ">=24.18.1 <25"
+	},
+	"packageManager": "pnpm@11.15.1",
+	"scripts": {
+		"build": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+		"check": "tsc --noEmit && biome check . && depcruise --config .dependency-cruiser.mjs 'src/**/*.ts' && node --test",
+		"test:workspace": "node tools/workspace-consumer.ts"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.7",
+		"@swc/core": "1.16.1",
+		"@types/node": "24.13.3",
+		"@zdreamer/forge-ts-service": "0.1.1",
+		"dependency-cruiser": "18.2.0",
+		"typescript": "7.0.2"
+	}
+}