frontend-project-context 1.7.0 → 1.8.0

package/src/project-context/exchange-schema.mjs

@@ -2,11 +2,11 @@ import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.
 import { fail } from "./errors.mjs";
 import { normalizeRelativePath } from "./path-policy.mjs";
 
-export const PACKAGE_VERSION = "1.7.0";
-export const EXCHANGE_PROTOCOL_VERSION = 7;
+export const PACKAGE_VERSION = "1.8.0";
+export const EXCHANGE_PROTOCOL_VERSION = 8;
 export const ACTION_PLAN_SCHEMA_VERSION = 2;
 export const REVIEW_BUNDLE_SCHEMA_VERSION = 2;
-export const CAPABILITIES_SCHEMA_VERSION = 7;
+export const CAPABILITIES_SCHEMA_VERSION = 8;
 
 export const ACTION_KINDS = Object.freeze([
   "accept-source-change",
@@ -24,7 +24,7 @@ export const ACTION_KINDS = Object.freeze([
 export const COMMANDS = Object.freeze([
   "accept-source-change", "approve", "capabilities", "check", "context", "context-query", "coverage-audit", "dashboard", "deprecate",
   "deprecate-source", "discover", "evidence", "init", "integration-review", "preflight", "propose", "publish", "register",
-  "index-context", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
+  "index-context", "instructions", "publish-entry", "remove-entry", "review-source", "revise", "setup", "stage-context", "status", "sync",
   "upgrade-apply", "upgrade-check", "upgrade-plan",
   "reconcile-truth",
 ]);

package/src/project-context/initialization-instruction.mjs

@@ -0,0 +1,42 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { sha256 } from "./canonical-json.mjs";
+import { PACKAGE_VERSION } from "./exchange-schema.mjs";
+
+export const INITIALIZATION_INSTRUCTION_SCHEMA_VERSION = 1;
+export const INITIALIZATION_INSTRUCTION_ID = "ai-project-initialization";
+export const INITIALIZATION_INSTRUCTION_VERSION = 1;
+export const INITIALIZATION_INSTRUCTION_PACKAGE_PATH = "docs/AI-PROJECT-INITIALIZATION.md";
+export const INITIALIZATION_INSTRUCTION_COMMAND = "project-context instructions --project PATH [--json | --prompt]";
+
+const INSTRUCTION_FILE = fileURLToPath(new URL(`../../${INITIALIZATION_INSTRUCTION_PACKAGE_PATH}`, import.meta.url));
+
+export async function readInitializationInstruction() {
+  const content = await readFile(INSTRUCTION_FILE, "utf8");
+  return {
+    id: INITIALIZATION_INSTRUCTION_ID,
+    version: INITIALIZATION_INSTRUCTION_VERSION,
+    packagePath: INITIALIZATION_INSTRUCTION_PACKAGE_PATH,
+    digest: sha256(content),
+    content,
+  };
+}
+
+export async function buildInitializationInstruction(targetRoot, boundaries) {
+  return {
+    schemaVersion: INITIALIZATION_INSTRUCTION_SCHEMA_VERSION,
+    package: { name: "frontend-project-context", version: PACKAGE_VERSION },
+    instruction: await readInitializationInstruction(),
+    targetRoot,
+    boundaries: { ...boundaries },
+  };
+}
+
+export function renderInitializationPrompt(result) {
+  return [
+    `<!-- frontend-project-context initialization instruction ${result.instruction.version}; ${result.instruction.digest} -->`,
+    `<!-- resolved-target-root: ${result.targetRoot} -->`,
+    result.instruction.content.trimEnd(),
+    "",
+  ].join("\n");
+}

package/src/project-context/migration-manifest.mjs

@@ -24,7 +24,7 @@ const ROLLBACK_CLASSES = new Set(["package-only", "reversible-data", "forward-on
 const CONSUMER_CHANGE_KEYS = new Set([
   "actionPlan", "adaptiveContextBundle", "capabilities", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
   "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt", "taskContextPlan",
-  "truthReconciliationInput", "truthReconciliationReviewBundle",
+  "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
 ]);
 
 function invalid(message, details) {
@@ -103,7 +103,7 @@ export function validateMigrationManifest(input) {
   ]), "migration manifest");
   if (manifest.schemaVersion !== MIGRATION_MANIFEST_SCHEMA_VERSION) invalid("migration manifest schemaVersion must be 2");
   exactKeys(manifest.package, new Set(["name", "version"]), "migration manifest package");
-  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.7.0") invalid("migration manifest package does not match this runtime");
+  if (manifest.package.name !== "frontend-project-context" || manifest.package.version !== "1.8.0") invalid("migration manifest package does not match this runtime");
   versions(manifest.upgradeFrom, "upgradeFrom");
   if (manifest.upgradeFrom.length === 0) invalid("upgradeFrom must not be empty");
   exactKeys(manifest.stores, new Set(["contract", "projectionLock", "proposal", "sourceLock"]), "stores");
@@ -113,7 +113,7 @@ export function validateMigrationManifest(input) {
   exactKeys(manifest.protocols, new Set([
     "exchange", "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "reviewBundle", "evidenceInput", "evidenceBundle", "taskContextPlan",
     "routingIndex", "stageReceipt", "stageContextBundle", "integrationReviewBundle", "hostPromotionEvidence",
-    "truthReconciliationInput", "truthReconciliationReviewBundle",
+    "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
   ]), "protocols");
   for (const name of Object.keys(manifest.protocols)) versionMatrix(manifest.protocols[name], `protocols.${name}`);
   if (!Array.isArray(manifest.builtInMigrations)) invalid("builtInMigrations must be an array");

package/src/project-context/project-status.mjs

@@ -4,8 +4,9 @@ import { checkExitCode, checkProject } from "./checker.mjs";
 import { ProjectContextError } from "./errors.mjs";
 import { PACKAGE_VERSION } from "./exchange-schema.mjs";
 import { inspectProjectInitialization, loadProject } from "./project-store.mjs";
+import { sourceStatus } from "./contract-schema.mjs";
 
-export const PROJECT_STATUS_SCHEMA_VERSION = 1;
+export const PROJECT_STATUS_SCHEMA_VERSION = 2;
 
 function uniqueSorted(values) {
   return [...new Set(values.filter((value) => value !== undefined && value !== null))]
@@ -46,6 +47,7 @@ function base(initialization, health, nextActions) {
     snapshots: null,
     health,
     entry: { state: "absent", path: null, rendererVersion: null },
+    contractReadiness: initialization === "uninitialized" ? "not-initialized" : "contract-incomplete",
     summary: emptySummary(),
     findingCodes: [],
     sourceIds: [],
@@ -65,7 +67,7 @@ function statusBoundaries(boundaries) {
 export async function buildProjectStatus(root, boundaries) {
   const initialization = await inspectProjectInitialization(root);
   if (initialization.status !== "initialized") {
-    const result = base(initialization.status, initialization.status, initialization.status === "uninitialized" ? ["run-setup-preview"] : ["resolve-conflict"]);
+    const result = base(initialization.status, initialization.status, initialization.status === "uninitialized" ? ["read-initialization-instructions"] : ["resolve-conflict"]);
     result.initialization.present = [...initialization.present];
     result.initialization.missing = [...initialization.missing];
     if (initialization.status === "partial") result.findingCodes = ["project-state-partial"];
@@ -112,7 +114,11 @@ export async function buildProjectStatus(root, boundaries) {
     if (sync.summary.affectedProjections > 0) nextActions.push("review-projection");
     if (entry.state !== "current") nextActions.push("publish-ai-entry");
     if (findings.length > 0 && nextActions.length === 0) nextActions.push("run-sync");
-    if (health === "clean") nextActions.push("ready-for-task");
+    if (health === "clean") {
+      const hasActiveSource = project.contract.sources.some((source) => sourceStatus(source) === "active");
+      const hasApprovedItem = project.contract.items.some((item) => item.status === "approved");
+      nextActions.push(hasActiveSource && hasApprovedItem && entry.state === "current" ? "compile-task-context" : "complete-onboarding");
+    }
   }
   const sourceIds = uniqueSorted([
     ...findings.flatMap((finding) => finding.source ? [finding.source] : []),
@@ -138,6 +144,11 @@ export async function buildProjectStatus(root, boundaries) {
     },
     health,
     entry,
+    contractReadiness: health === "clean" && entry.state === "current" &&
+      project.contract.sources.some((source) => sourceStatus(source) === "active") &&
+      project.contract.items.some((item) => item.status === "approved")
+      ? "contract-ready"
+      : "contract-incomplete",
     summary: {
       findings: findings.length,
       changedSources: sync.summary.changedSources,

package/src/project-context/project-store.mjs

@@ -1,4 +1,4 @@
-import { access, mkdir, rename, rm } from "node:fs/promises";
+import { access, lstat, mkdir, readdir, rename, rm, rmdir } from "node:fs/promises";
 import path from "node:path";
 import { randomBytes } from "node:crypto";
 import { canonicalJson, digestJson } from "./canonical-json.mjs";
@@ -43,8 +43,20 @@ async function exists(filePath) {
   }
 }
 
+async function isEmptyDirectory(filePath) {
+  try {
+    const stats = await lstat(filePath);
+    if (!stats.isDirectory()) return false;
+    return (await readdir(filePath)).length === 0;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 export async function inspectProjectInitialization(root) {
   const files = projectFiles(root);
+  const emptyContainer = await isEmptyDirectory(files.directory);
   const entries = [
     [CONTEXT_DIRECTORY, files.directory],
     [`${CONTEXT_DIRECTORY}/${CONTRACT_FILE}`, files.contract],
@@ -53,6 +65,7 @@ export async function inspectProjectInitialization(root) {
   ];
   const present = [];
   for (const [relative, absolute] of entries) {
+    if (relative === CONTEXT_DIRECTORY && emptyContainer) continue;
     if (await exists(absolute)) present.push(relative);
   }
   const storePaths = entries.slice(1).map(([relative]) => relative);
@@ -71,8 +84,9 @@ export async function initializeProject(root, id, name, write) {
   validateContract(initial.contract);
   validateSourceLock(initial.sourcesLock);
   validateProjectionLock(initial.projectionsLock);
+  const emptyContainer = await isEmptyDirectory(files.directory);
   const existing = [];
-  if (await exists(files.directory)) existing.push(CONTEXT_DIRECTORY);
+  if ((await exists(files.directory)) && !emptyContainer) existing.push(CONTEXT_DIRECTORY);
   for (const filePath of [files.contract, files.sourcesLock, files.projectionsLock]) {
     if (await exists(filePath)) existing.push(path.relative(root, filePath));
   }
@@ -80,6 +94,17 @@ export async function initializeProject(root, id, name, write) {
     fail("project-already-initialized", "project context files already exist", { details: { paths: existing } });
   }
   if (write) {
+    if (emptyContainer) {
+      try {
+        await rmdir(files.directory);
+      } catch (error) {
+        if (error?.code !== "ENOENT") {
+          fail("project-already-initialized", "project context directory changed before initialization", {
+            details: { paths: [CONTEXT_DIRECTORY] },
+          });
+        }
+      }
+    }
     const temporaryDirectory = `${files.directory}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
     try {
       await mkdir(temporaryDirectory, { recursive: false });

package/src/project-context/upgrade-schema.mjs

@@ -123,7 +123,7 @@ export function validateUpgradeAssessment(input) {
     protocols: new Set([
       "actionPlan", "adaptiveContextBundle", "contextQuery", "coverageAudit", "evidenceBundle", "evidenceInput", "exchange",
       "hostPromotionEvidence", "integrationReviewBundle", "reviewBundle", "routingIndex", "stageContextBundle", "stageReceipt",
-      "taskContextPlan", "truthReconciliationInput", "truthReconciliationReviewBundle",
+      "taskContextPlan", "truthReconciliationInput", "truthReconciliationReviewBundle", "initializationInstruction", "projectStatus",
     ]),
   };
   for (const [name, group] of Object.entries(value.compatibility)) {