@jakkrichm/create-nexus-devflow 2.0.0

package/lib/update.js

@@ -0,0 +1,379 @@
+const crypto = require("node:crypto");
+const fs = require("node:fs/promises");
+const path = require("node:path");
+
+const CONTROL_DIR = ".nexus";
+const MANIFEST_PATH = `${CONTROL_DIR}/nexus-devflow.json`;
+const MANIFEST_SCHEMA_VERSION = 1;
+const MANAGED_ROOTS = {
+  common: ["AGENTS.md", "CLAUDE.md", "devflow", "LICENSE"],
+  codex: [".agents/skills"],
+  antigravity: [".agents/skills", ".agent/workflows"],
+  claude: [".claude/skills"]
+};
+
+function adapterListFromMode(adapter) {
+  if (adapter === "both" || adapter === "all") {
+    return ["codex", "claude"];
+  }
+
+  if (adapter === "antigravity") {
+    return ["codex"];
+  }
+
+  if (adapter === "codex" || adapter === "claude") {
+    return [adapter];
+  }
+
+  throw new Error(`Unknown adapter mode: ${adapter}`);
+}
+
+function createManifest(version, adapters, templateFiles) {
+  const managedFiles = {};
+
+  for (const [relativePath, file] of [...templateFiles.entries()].sort(([a], [b]) =>
+    a.localeCompare(b)
+  )) {
+    managedFiles[relativePath] = file.hash;
+  }
+
+  return {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    name: "nexus-devflow",
+    package: "@jakkrichm/create-nexus-devflow",
+    version,
+    repository: "https://github.com/Jakkrich/nexus-devflow",
+    artifactLanguage: "th",
+    adapters: [...adapters].sort(),
+    workspace: {
+      contextDir: "devflow/context",
+      historyDir: "devflow/history",
+      referenceDir: "devflow/reference",
+      runsDir: "devflow/runs",
+      discoveriesDir: "devflow/discoveries"
+    },
+    lifecycle: {
+      mainlineStages: [
+        "00-discover",
+        "10-define",
+        "20-spec",
+        "30-plan",
+        "40-implement",
+        "50-verify",
+        "60-report",
+        "70-release"
+      ],
+      companionCommands: [
+        "goal",
+        "brainstorm",
+        "research",
+        "debug",
+        "prd",
+        "issue-triage",
+        "security-review",
+        "wiki",
+        "check-for-updates",
+        "help"
+      ]
+    },
+    managedFiles
+  };
+}
+
+async function collectManagedTemplateFiles(templateRoot, adapters) {
+  const files = new Map();
+  const roots = [
+    ...MANAGED_ROOTS.common,
+    ...adapters.flatMap((adapter) => MANAGED_ROOTS[adapter] || [])
+  ];
+
+  for (const relativeRoot of roots) {
+    const sourceRoot = path.join(templateRoot, ...relativeRoot.split("/"));
+    await collectSourceFiles(sourceRoot, relativeRoot, files);
+  }
+
+  return files;
+}
+
+async function collectSourceFiles(sourcePath, relativePath, files) {
+  try {
+    const stats = await fs.lstat(sourcePath);
+
+    if (stats.isSymbolicLink()) {
+      throw new Error(`Managed template path cannot be a symbolic link: ${relativePath}`);
+    }
+
+    if (stats.isDirectory()) {
+      const children = (await fs.readdir(sourcePath)).sort();
+
+      for (const child of children) {
+        await collectSourceFiles(
+          path.join(sourcePath, child),
+          `${relativePath}/${child}`,
+          files
+        );
+      }
+
+      return;
+    }
+
+    if (!stats.isFile()) {
+      throw new Error(`Managed template path is not a regular file: ${relativePath}`);
+    }
+
+    files.set(relativePath, {
+      source: sourcePath,
+      hash: await hashFile(sourcePath)
+    });
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
+}
+
+async function readManifest(targetDir) {
+  const manifestFile = targetPath(targetDir, MANIFEST_PATH);
+  await assertNoSymlinkParents(targetDir, MANIFEST_PATH);
+
+  try {
+    const content = await fs.readFile(manifestFile, "utf8");
+    const data = JSON.parse(content);
+
+    if (!data || data.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+      throw new Error("Unsupported manifest schema version.");
+    }
+
+    return data;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function prepareUpdate({ targetDir, templateRoot, version, adapter }) {
+  const requestedAdapters = new Set(adapterListFromMode(adapter));
+  const previousManifest = await readManifest(targetDir);
+
+  const activeAdapters = new Set([
+    ...requestedAdapters,
+    ...(previousManifest?.adapters || [])
+  ]);
+
+  const templateFiles = await collectManagedTemplateFiles(
+    templateRoot,
+    [...activeAdapters]
+  );
+  const nextManifest = createManifest(version, activeAdapters, templateFiles);
+
+  const createList = [];
+  const updateList = [];
+  const conflictList = [];
+
+  for (const [relativePath, templateFile] of templateFiles) {
+    await assertNoSymlinkParents(targetDir, relativePath);
+    const targetFile = targetPath(targetDir, relativePath);
+
+    let targetStats = null;
+    try {
+      targetStats = await fs.lstat(targetFile);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    if (!targetStats) {
+      createList.push(relativePath);
+      continue;
+    }
+
+    if (targetStats.isSymbolicLink()) {
+      conflictList.push({
+        relativePath,
+        reason: "symlink",
+        detail: "Target path is a symbolic link."
+      });
+      continue;
+    }
+
+    if (!targetStats.isFile()) {
+      conflictList.push({
+        relativePath,
+        reason: "not_file",
+        detail: "Target path exists but is not a regular file."
+      });
+      continue;
+    }
+
+    const currentHash = await hashFile(targetFile);
+    if (currentHash === templateFile.hash) {
+      continue;
+    }
+
+    const recordedHash = previousManifest?.managedFiles?.[relativePath];
+    if (recordedHash && recordedHash === currentHash) {
+      updateList.push(relativePath);
+      continue;
+    }
+
+    conflictList.push({
+      relativePath,
+      reason: "customized",
+      detail: recordedHash
+        ? "File was modified locally since last install."
+        : "File exists in project and differs from template."
+    });
+  }
+
+  const orphanedFiles = [];
+  if (previousManifest) {
+    for (const [relativePath, recordedHash] of Object.entries(
+      previousManifest.managedFiles
+    )) {
+      if (templateFiles.has(relativePath)) {
+        continue;
+      }
+
+      await assertNoSymlinkParents(targetDir, relativePath);
+      const targetFile = targetPath(targetDir, relativePath);
+
+      let targetStats = null;
+      try {
+        targetStats = await fs.lstat(targetFile);
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          throw error;
+        }
+      }
+
+      if (!targetStats || !targetStats.isFile()) {
+        continue;
+      }
+
+      const currentHash = await hashFile(targetFile);
+      if (currentHash === recordedHash) {
+        orphanedFiles.push(relativePath);
+      }
+    }
+  }
+
+  return {
+    targetDir,
+    templateRoot,
+    previousManifest,
+    nextManifest,
+    activeAdapters: [...activeAdapters].sort(),
+    templateFiles,
+    createList,
+    updateList,
+    conflictList,
+    orphanedFiles
+  };
+}
+
+async function applyPreparedUpdate(prepared, { replaceConflicts = false } = {}) {
+  if (prepared.conflictList.length > 0 && !replaceConflicts) {
+    throw new Error(
+      `Cannot apply update with ${prepared.conflictList.length} conflict(s). Pass force/replace option or resolve conflicts.`
+    );
+  }
+
+  const writeTargets = [
+    ...prepared.createList,
+    ...prepared.updateList,
+    ...(replaceConflicts ? prepared.conflictList.map((item) => item.relativePath) : [])
+  ];
+
+  let appliedCount = 0;
+  for (const relativePath of writeTargets) {
+    const templateFile = prepared.templateFiles.get(relativePath);
+    if (!templateFile) {
+      continue;
+    }
+
+    await copyFileAtomic(prepared.targetDir, relativePath, templateFile.source);
+    appliedCount++;
+  }
+
+  let removedCount = 0;
+  for (const relativePath of prepared.orphanedFiles) {
+    const fileToRemove = targetPath(prepared.targetDir, relativePath);
+    try {
+      await fs.unlink(fileToRemove);
+      removedCount++;
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+  }
+
+  await writeInstallManifest(prepared.targetDir, prepared.nextManifest);
+
+  return {
+    appliedCount,
+    removedCount
+  };
+}
+
+async function writeInstallManifest(targetDir, manifest) {
+  const manifestFile = targetPath(targetDir, MANIFEST_PATH);
+  await fs.mkdir(path.dirname(manifestFile), { recursive: true });
+  await fs.writeFile(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+async function copyFileAtomic(targetDir, relativePath, sourcePath) {
+  await assertNoSymlinkParents(targetDir, relativePath);
+  const destinationPath = targetPath(targetDir, relativePath);
+  await fs.mkdir(path.dirname(destinationPath), { recursive: true });
+
+  const tempPath = `${destinationPath}.tmp-${process.pid}-${Date.now()}`;
+  await fs.copyFile(sourcePath, tempPath);
+  await fs.rename(tempPath, destinationPath);
+}
+
+function targetPath(targetDir, relativePath) {
+  return path.resolve(targetDir, ...relativePath.split("/"));
+}
+
+async function assertNoSymlinkParents(targetDir, relativePath) {
+  const parts = relativePath.split("/");
+  let current = path.resolve(targetDir);
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    current = path.join(current, parts[i]);
+    try {
+      const stats = await fs.lstat(current);
+      if (stats.isSymbolicLink()) {
+        throw new Error(
+          `Target sub-path "${parts.slice(0, i + 1).join("/")}" is a symbolic link.`
+        );
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        break;
+      }
+      throw error;
+    }
+  }
+}
+
+async function hashFile(filePath) {
+  const content = await fs.readFile(filePath);
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+module.exports = {
+  CONTROL_DIR,
+  MANIFEST_PATH,
+  adapterListFromMode,
+  applyPreparedUpdate,
+  createManifest,
+  prepareUpdate,
+  readManifest,
+  writeInstallManifest
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@jakkrichm/create-nexus-devflow",
+  "version": "2.0.0",
+  "description": "Install or update the agent-ready DevFlow 2.0 workflow layer into a scaffolded or existing project.",
+  "license": "MIT",
+  "author": "Jakkrich",
+  "homepage": "https://github.com/Jakkrich/nexus-devflow#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jakkrich/nexus-devflow.git",
+    "directory": "packages/create-nexus-devflow"
+  },
+  "bugs": {
+    "url": "https://github.com/Jakkrich/nexus-devflow/issues"
+  },
+  "keywords": [
+    "devflow",
+    "nexus-devflow",
+    "ai",
+    "ai-coding",
+    "antigravity",
+    "codex",
+    "claude-code",
+    "agent",
+    "workflow",
+    "scaffold"
+  ],
+  "bin": {
+    "create-nexus-devflow": "bin/create-nexus-devflow.js",
+    "nexus-devflow": "bin/create-nexus-devflow.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "check:pack": "npm pack --dry-run",
+    "prepare-template": "node scripts/prepare-template.js",
+    "prepack": "node scripts/prepare-template.js",
+    "postpack": "node scripts/clean-template.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "template/",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/template/.agents/skills/00-discover/SKILL.md

@@ -0,0 +1,170 @@
+---name: 00-discover
+
+description: Discover stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID.
+argument-hint: "{title, request, or discovery-id}"
+---
+
+# Phase 00: Discover
+
+$ARGUMENTS
+
+Explore a request before delivery commitment. Create or resume a Discovery ID, choose only the supporting route that the uncertainty requires, and finish with a visible `Proceed`, `Defer`, or `Reject` decision. Do not create a Running ID in this stage.
+
+## Usage
+
+```text
+/00-Discover {title or request}
+/00-Discover {discovery-id}
+```
+
+Use this when:
+
+- a new request needs discussion before the team commits to delivery
+- the best route may be `Brainstorm`, `PRD`, `Research`, or `Debug`
+- supporting findings need to be synthesized into a go/no-go decision
+
+## Markdown-First Contract
+
+Write the primary discovery artifact to:
+
+```text
+devflow/discoveries/{DISCOVERY_ID}-{slug}/00-discover.md
+```
+
+using:
+
+```text
+.agent/resources/schemas/discover.template.md
+```
+
+Before writing `00-discover.md`, read `artifact_language` from `discover.template.md` and produce the artifact in that language.
+
+A Discovery ID uses a separate namespace such as `DISC-YYYYMMDD-NNN`. It is not a Running ID and must not reserve a numeric delivery run.
+
+## Required Section Content
+
+Before completing any generated artifact:
+
+- preserve every heading required by the selected template
+- write concrete information under every heading
+- when no information exists or the section does not apply, write exactly `-`
+- never leave a heading immediately followed by another heading with no body content
+- remove template placeholders from the final artifact
+- do not invent facts merely to avoid using `-`
+- re-read the saved artifact and verify every heading satisfies this rule
+
+## Process
+
+### Loop Contract
+
+Run discovery as a decision-and-routing loop, not as task initialization.
+
+- **Intent**: understand the request, select proportionate supporting inquiry, and decide whether the idea should enter delivery definition.
+- **Context**: read the request, the discovery artifact when resuming, companion outputs, project context, constraints, and available evidence.
+- **Action**: restate the problem, identify the decision-blocking uncertainty, select `Brainstorm`, `PRD`, `Research`, `Debug`, or direct decision, then synthesize returned findings.
+- **Observation**: use concrete evidence such as option tradeoffs, product framing, research results, root cause, stakeholder constraints, open questions, and visible risk.
+- **Adjustment**: invoke only the companion route needed to resolve the current uncertainty; every companion invoked by Discover must return to this Discovery ID for synthesis.
+- **Stop Condition**: stop when the selected route and evidence are recorded, open questions are visible, and the decision is `Proceed`, `Defer`, or `Reject`.
+- **Handoff**: only an approved `Proceed` discovery may hand off to `/10-Define {discovery_id}`. `Defer` and `Reject` end without allocating a Running ID.
+
+### 1. Create Or Resume The Discovery
+
+- inspect `devflow/discoveries/`
+- create a collision-free Discovery ID or resume the one supplied
+- generate a stable slug
+- do not inspect or increment numeric Running IDs during this stage
+
+### 2. Ground The Request
+
+- restate the request in plain language
+- identify the affected users, stakeholders, or systems
+- capture known constraints and decision-blocking unknowns
+- distinguish an idea worth exploring from delivery work already approved elsewhere
+
+### 3. Select The Supporting Route
+
+Choose proportionally:
+
+- `Brainstorm` when several viable directions need comparison
+- `PRD` when user value, product outcomes, MVP boundaries, or success measures need framing
+- `Research` when facts, codebase evidence, feasibility, or external constraints are missing
+- `Debug` when the request begins with a failure and root cause is unknown
+- direct decision when the request and evidence are already clear
+
+Routes are not mutually exclusive, but do not stack them by default. Record why each selected route is necessary. Pass the Discovery ID to the companion and require its output to link back to the discovery.
+
+### 4. Synthesize Returned Findings
+
+After each companion route:
+
+- update `00-discover.md` with the durable findings and source path
+- reassess whether another route is materially necessary
+- return to the Discover decision rather than jumping directly to `/10-Define`
+
+### 5. Decide
+
+Set one decision:
+
+- `Proceed`: enough value and evidence exist to define delivery work
+- `Defer`: the idea remains relevant but timing, evidence, or ownership is not ready
+- `Reject`: the idea should not proceed under the current framing
+
+Candidate delivery slices may be suggested, but they remain provisional and unnumbered until `/10-Define`.
+
+### 6. Write `00-discover.md`
+
+- preserve the template headings
+- follow the configured `artifact_language`
+- replace placeholders with concrete context
+- record selected routes, returned findings, open questions, decision, and rationale
+- keep `related_runs` empty until `/10-Define` materializes approved slices
+
+### 7. Manual Review Gate
+
+Before `/10-Define`:
+
+- confirm the selected route and evidence are sufficient
+- confirm the decision is `Proceed`
+- set `Approval Status` to `Approved`
+
+Do not allocate Running IDs when the decision or approval is pending.
+
+## Output
+
+Report:
+
+- Discovery ID and artifact path
+- request and problem summary
+- selected support route and why
+- important findings and open questions
+- `Proceed`, `Defer`, or `Reject` decision
+- recommended next step, including `/10-Define {discovery_id}` only when Proceed is approved
+
+## Relationship To DevFlow 2.0
+
+- Classification: Mainline discovery stage
+- Previous state: request intake
+- Next state: `/10-Define {discovery_id}` only after approved Proceed
+- Common companion routes: `Brainstorm`, `PRD`, `Research`, `Debug`
+- Running ID lifecycle: begins in `/10-Define`, not in Discover
+
+## Sources
+
+- `AGENTS.md`
+- `docs/workspace-artifacts.md`
+- `.agent/resources/schemas/discover.template.md`
+
+## Next Workflow Recommendation
+
+- **Primary**: the selected companion route, or `/10-Define {discovery_id}` after approved Proceed
+- **Alternatives**:
+  - `Brainstorm {discovery_id}` for unresolved options
+  - `PRD {discovery_id}` for product framing
+  - `Research {discovery_id}` for missing evidence
+  - `Debug {discovery_id}` for unknown root cause
+  - no next command when the decision is Defer or Reject
+
+## Nexus Event
+
+- Use `grill-with-docs` when focused clarification could change the decision or selected route.
+- Use `prototype` when runnable evidence is the fastest way to settle feasibility.