@graphrefly/stack 0.1.0 → 0.1.1

package/README.md

@@ -21,14 +21,13 @@ GraphReFly repository you want to review:
 ```bash
 pnpm add -D @graphrefly/stack
 pnpm exec grfs init --graph-module src/application-graph.ts
-git add .graphrefly-stack.json graphrefly-stack.blueprint.mjs
-git commit -m "configure GraphReFly Stack"
 
 BASE=<the commit immediately before your stack>
 pnpm exec grfs review --repo . --base "$BASE" --head HEAD
 ```
 
-Open <http://127.0.0.1:4173>, then:
+The review command stays running and prints its loopback URL; it does not launch a browser
+automatically. Open the printed URL (normally <http://127.0.0.1:4173>), then:
 
 1. Select each commit discovered from the real linear Git range.
 2. See the Blueprint and parent delta produced by the repository's installed GraphReFly 0.3.x
@@ -38,15 +37,28 @@ Open <http://127.0.0.1:4173>, then:
 4. Expand repository evidence or commit lineage only when needed. No session, delivery, fixture, or
    fake semantic-gate state appears in the generic review.
 
-`grfs init` does not guess how an arbitrary application assembles its graph. You point it at the
-module and export that already build the repository's root Graph. It generates the strict
-`.graphrefly-stack.json` config and a small deterministic `graphrefly-stack.blueprint.mjs` adapter;
-both are ordinary source files that should be committed. Use `--graph-export <name>` when the module
-does not export `createApplicationGraph`.
-
-The CLI executes that generated adapter at the base and every commit in permission-limited detached
-worktrees. Each invocation calls the real GraphReFly `graph.blueprint()` API; Stack then parses,
-verifies, renders, and diffs only with the installed runtime's public GraphReFly APIs.
+`--graph-module` means the repository's root Graph construction module, not the only Graph module
+allowed in the repository. That root module may import, compose, and mount any number of Graphs and
+subgraphs. The first version reviews one configured root Blueprint target at a time; selecting among
+multiple independent application roots in a monorepo is roadmap work.
+
+`grfs init` does not guess how an arbitrary application assembles that root Graph. You point it at
+the module and export that already construct it once during onboarding. The command generates the
+strict `.graphrefly-stack.json` config and a small deterministic
+`graphrefly-stack.blueprint.mjs` adapter; both are ordinary source files that should be committed.
+Use `--graph-export <name>` when the module does not export `createApplicationGraph`. JSON is the v1
+configuration format; optional YAML and TOML authoring formats are deferred roadmap work and must
+normalize to the same strict configuration contract before execution.
+
+Initialization may happen after the stack already exists. The review snapshots the configured
+adapter and supplies those same bounded bytes only inside isolated detached revisions where that
+entrypoint did not exist yet; it does not rewrite repository history. The referenced root Graph
+module must exist at every reviewed revision. Commit the config and adapter after onboarding so
+future reviews have a Git-owned configuration witness.
+
+The CLI executes the adapter at the base and every commit in permission-limited detached worktrees.
+Each invocation calls the real GraphReFly `graph.blueprint()` API; Stack then parses, verifies,
+renders, and diffs only with the installed runtime's public GraphReFly APIs.
 
 ## Generic repository contract
 

package/dist/grfs.js

@@ -8563,6 +8563,7 @@ var require_semver2 = __commonJS({
 });
 
 // packages/cli/dist/cli.js
+import { realpathSync } from "node:fs";
 import { readFile as readFile7 } from "node:fs/promises";
 import { resolve as resolve10 } from "node:path";
 import { pathToFileURL as pathToFileURL3 } from "node:url";
@@ -10149,7 +10150,7 @@ process.stdout.write(JSON.stringify(blueprint));
 // packages/cli/dist/repository-review.js
 import { spawnSync as spawnSync5 } from "node:child_process";
 import { createHash as createHash6 } from "node:crypto";
-import { access as access2, mkdir as mkdir5, readFile as readFile6, realpath as realpath3, rm as rm4, symlink } from "node:fs/promises";
+import { access as access2, mkdir as mkdir5, readFile as readFile6, realpath as realpath3, rm as rm4, symlink, writeFile as writeFile5 } from "node:fs/promises";
 import { createRequire as createRequire2 } from "node:module";
 import { basename as basename2, dirname as dirname5, parse, resolve as resolve8, sep as sep4 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
@@ -10283,6 +10284,7 @@ var reviewSchemaPath = runtimeAssetPath("contracts/repository/v1/review.schema.j
 var configName2 = ".graphrefly-stack.json";
 var lockCandidates = ["pnpm-lock.yaml", "package-lock.json", "yarn.lock"];
 var maxReviewCommits = 64;
+var maxEntrypointBytes = 64 * 1024;
 var RepositoryReviewError = class extends Error {
   code;
   constructor(code, message) {
@@ -10365,6 +10367,22 @@ function ensureInside(root, candidate) {
     throw new RepositoryReviewError("ENTRYPOINT_ESCAPE", "Blueprint entrypoint escapes the worktree");
   }
 }
+async function readConfiguredEntrypoint(repository, entrypointPath) {
+  const entrypoint = resolve8(repository, entrypointPath);
+  ensureInside(repository, entrypoint);
+  let canonicalEntrypoint;
+  try {
+    canonicalEntrypoint = await realpath3(entrypoint);
+  } catch {
+    throw new RepositoryReviewError("ENTRYPOINT_MISSING", "Configured Blueprint entrypoint is missing");
+  }
+  ensureInside(repository, canonicalEntrypoint);
+  const source = await readFile6(canonicalEntrypoint);
+  if (source.byteLength > maxEntrypointBytes) {
+    throw new RepositoryReviewError("ENTRYPOINT_TOO_LARGE", `Configured Blueprint entrypoint exceeds ${maxEntrypointBytes} bytes`);
+  }
+  return source;
+}
 function containsAbsolutePath(value) {
   if (typeof value === "string")
     return value.startsWith("/") || /^[A-Za-z]:[\\/]/u.test(value);
@@ -10416,7 +10434,7 @@ async function resolveTargetRuntime(repository) {
     diffGraphBlueprints: graphModule.diffGraphBlueprints
   };
 }
-async function executeBlueprint(repository, revision, entrypointPath, runtime) {
+async function executeBlueprint(repository, revision, entrypointPath, entrypointSource, runtime) {
   const worktreeRoot = resolve8(dirname5(repository), `.graphrefly-stack-review-${basename2(repository)}-${process.pid}`);
   const worktree = resolve8(worktreeRoot, revision.slice(0, 16));
   await mkdir5(worktreeRoot, { recursive: true });
@@ -10429,8 +10447,19 @@ async function executeBlueprint(repository, revision, entrypointPath, runtime) {
     try {
       await access2(entrypoint);
     } catch {
-      throw new RepositoryReviewError("ENTRYPOINT_MISSING", `Blueprint entrypoint is missing at ${revision.slice(0, 12)}`);
+      let canonicalParent;
+      try {
+        canonicalParent = await realpath3(dirname5(entrypoint));
+      } catch {
+        throw new RepositoryReviewError("ENTRYPOINT_MISSING", `Blueprint entrypoint parent is missing at ${revision.slice(0, 12)}`);
+      }
+      ensureInside(canonicalWorktree, canonicalParent);
+      await writeFile5(resolve8(canonicalParent, basename2(entrypoint)), entrypointSource, {
+        flag: "wx"
+      });
     }
+    const canonicalEntrypoint = await realpath3(entrypoint);
+    ensureInside(canonicalWorktree, canonicalEntrypoint);
     const worktreeNodeModules = resolve8(canonicalWorktree, "node_modules");
     await rm4(worktreeNodeModules, { recursive: true, force: true });
     await symlink(runtime.nodeModulesRoot, worktreeNodeModules, "dir");
@@ -10439,7 +10468,7 @@ async function executeBlueprint(repository, revision, entrypointPath, runtime) {
       `--allow-fs-read=${canonicalWorktree}`,
       `--allow-fs-read=${runtime.nodeModulesRoot}`,
       "--disable-warning=ExperimentalWarning",
-      entrypoint
+      canonicalEntrypoint
     ], {
       cwd: canonicalWorktree,
       encoding: "utf8",
@@ -10552,6 +10581,7 @@ async function createRepositoryReview(options) {
     throw new RepositoryReviewError("REPOSITORY_INVALID", "Repository must be a local Git worktree");
   }
   const config = await readRepositoryConfig(repository);
+  const entrypointSource = await readConfiguredEntrypoint(repository, config.blueprint.entrypoint);
   const git2 = new SystemGitAdapter();
   let baseOid;
   let headOid;
@@ -10595,7 +10625,7 @@ async function createRepositoryReview(options) {
   await validateDependencyContinuity(repository, allRevisions, runtime.version);
   const evidence = [];
   for (const revision of allRevisions) {
-    const blueprint = await executeBlueprint(repository, revision, config.blueprint.entrypoint, runtime);
+    const blueprint = await executeBlueprint(repository, revision, config.blueprint.entrypoint, entrypointSource, runtime);
     evidence.push({
       oid: revision,
       subject: gitText(repository, ["show", "-s", "--format=%s", revision]),
@@ -11079,7 +11109,11 @@ ${help}`);
   process.once("SIGTERM", close);
   return 0;
 }
-var entry = process.argv[1] ? pathToFileURL3(process.argv[1]).href : "";
+var entry = "";
+try {
+  entry = process.argv[1] ? pathToFileURL3(realpathSync(process.argv[1])).href : "";
+} catch {
+}
 if (import.meta.url === entry) {
   runCli().then((code) => {
     process.exitCode = code;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@graphrefly/stack",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"private": false,
 	"description": "Semantic stacked diffs with commit-indexed GraphBlueprint validity gates.",
 	"license": "MIT",