architectonic 0.0.5 → 0.0.6

package/README.md

@@ -16,6 +16,8 @@ The initial placeholder releases were intentionally minimal. Starting in
 local manifest, repair light manifest drift, update safely, and remove layers
 without trampling local forks.
 
+Starting in `0.0.6`, it can also inspect drift with `status` and `diff`.
+
 ## Command shape
 
 The primary interaction model is:
@@ -28,6 +30,8 @@ architectonic add skills
 architectonic add teleology identity skills
 architectonic init
 architectonic doctor
+architectonic status
+architectonic diff
 architectonic list
 architectonic update
 architectonic remove
@@ -53,6 +57,8 @@ npx architectonic init --preset company
 npx architectonic list
 npx architectonic doctor
 npx architectonic doctor --fix
+npx architectonic status
+npx architectonic diff teleology
 npx architectonic update
 npx architectonic update --dry-run
 npx architectonic remove skills
@@ -99,6 +105,20 @@ ARCHITECTONIC_ADD_SOURCE    # change the default source mode
 package metadata matches the expected layer. `doctor --fix` repairs light
 manifest drift such as stale package names or recoverable default paths.
 
+`status` gives a read-only summary of each layer:
+
+```text
+git layers: branch, dirty/clean, ahead/behind upstream
+npm layers: installed version vs published version
+```
+
+`diff <layer>` drills into one layer:
+
+```text
+git layers: local status lines plus ahead/behind numbers
+npm layers: installed version vs published version
+```
+
 `init` creates a workspace root, installs a preset, and seeds a top-level
 `README.md` and `AGENTS.md`.
 

package/bin/architectonic.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 
-const VERSION = "0.0.5";
+const VERSION = "0.0.6";
 const args = process.argv.slice(2);
 const [command, ...rest] = args;
 const supported = ["teleology", "identity", "project", "skills"];
@@ -34,6 +34,8 @@ Usage:
   npx architectonic list
   npx architectonic doctor
   npx architectonic doctor --fix
+  npx architectonic status
+  npx architectonic diff <layer>
   npx architectonic update
   npx architectonic remove <layer>
 
@@ -50,7 +52,10 @@ Run vs install:
 
 What add does:
   Installs the selected layer repositories into the target directory
-  from git or npm sources and records them in architectonic.json.`);
+  from git or npm sources and records them in architectonic.json.
+
+What status and diff do:
+  Inspect local drift from recorded sources without mutating anything.`);
 }
 
 function printUsageError(message) {
@@ -209,6 +214,56 @@ function parseUpdateArgs(tokens) {
   return { installDir, dryRun };
 }
 
+function parseStatusArgs(tokens) {
+  let installDir = process.cwd();
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    installDir = path.resolve(token);
+  }
+
+  return { installDir };
+}
+
+function parseDiffArgs(tokens) {
+  let installDir = process.cwd();
+  let target = "";
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "--dir" || token === "--out") {
+      const next = tokens[index + 1];
+      if (!next) {
+        throw new Error(`Missing value for ${token}`);
+      }
+      installDir = path.resolve(next);
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("--dir=")) {
+      installDir = path.resolve(token.slice("--dir=".length));
+      continue;
+    }
+    if (token.startsWith("--out=")) {
+      installDir = path.resolve(token.slice("--out=".length));
+      continue;
+    }
+    if (token.startsWith("-")) {
+      throw new Error(`Unknown option: ${token}`);
+    }
+    if (!target) {
+      target = token;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${token}`);
+  }
+
+  return { installDir, target };
+}
+
 function parseRemoveArgs(tokens) {
   let installDir = process.cwd();
   let force = false;
@@ -497,6 +552,95 @@ function updateManifestLayerRecord(manifest, installDir, layerName, absoluteLaye
   };
 }
 
+function getGitHead(layerPath) {
+  const result = gitResult(["rev-parse", "HEAD"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function getGitBranch(layerPath) {
+  const result = gitResult(["rev-parse", "--abbrev-ref", "HEAD"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function getGitUpstream(layerPath) {
+  const result = gitResult(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function getGitAheadBehind(layerPath) {
+  const upstream = getGitUpstream(layerPath);
+  if (!upstream) {
+    return null;
+  }
+  const result = gitResult(["rev-list", "--left-right", "--count", `${upstream}...HEAD`], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  const [behindRaw, aheadRaw] = (result.stdout || "").trim().split(/\s+/);
+  return {
+    upstream,
+    behind: Number.parseInt(behindRaw || "0", 10),
+    ahead: Number.parseInt(aheadRaw || "0", 10),
+  };
+}
+
+function getGitDiffSummary(layerPath) {
+  const result = gitResult(["status", "--short"], layerPath);
+  if (result.status !== 0) {
+    return null;
+  }
+  const lines = (result.stdout || "").split(/\r?\n/).filter(Boolean);
+  return {
+    dirty: lines.length > 0,
+    lines,
+  };
+}
+
+function getNpmPublishedVersion(packageSpec) {
+  const result = spawnSync("npm", ["view", packageSpec, "version"], {
+    encoding: "utf8",
+    stdio: "pipe",
+    shell: true,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  return (result.stdout || "").trim() || null;
+}
+
+function describeGitLayerState(layerPath) {
+  const branch = getGitBranch(layerPath);
+  const head = getGitHead(layerPath);
+  const diffSummary = getGitDiffSummary(layerPath);
+  const aheadBehind = getGitAheadBehind(layerPath);
+  return {
+    branch,
+    head,
+    dirty: diffSummary?.dirty ?? false,
+    diffLines: diffSummary?.lines ?? [],
+    aheadBehind,
+  };
+}
+
+function describeNpmLayerState(layerName, layerPath) {
+  const installedVersion = readInstalledVersion(layerPath);
+  const publishedVersion = getNpmPublishedVersion(packageSpecFor(layerName));
+  return {
+    installedVersion,
+    publishedVersion,
+    outdated: Boolean(installedVersion && publishedVersion && installedVersion !== publishedVersion),
+  };
+}
+
 function installTargets(targets, installDir, source) {
   ensureInstallPrereqs(source);
   fs.mkdirSync(installDir, { recursive: true });
@@ -626,6 +770,54 @@ function listCommand(tokens) {
   }
 }
 
+function statusCommand(tokens) {
+  const { installDir } = parseStatusArgs(tokens);
+  const { manifest } = loadManifestFromDir(installDir);
+  const entries = Object.entries(manifest.layers || {});
+
+  if (!entries.length) {
+    console.log("No layers installed.");
+    return;
+  }
+
+  ensureGitAvailable();
+  ensureNpmAvailable();
+
+  console.log(`architectonic status`);
+  console.log(`  root: ${installDir}`);
+
+  for (const [name, layer] of entries) {
+    const layerPath = path.resolve(installDir, String(layer.path || ""));
+    if (!pathExists(layerPath)) {
+      console.log(`  [missing] ${name}: ${layer.path || "unknown path"}`);
+      continue;
+    }
+
+    if (layer.source === "git") {
+      const state = describeGitLayerState(layerPath);
+      const dirtyLabel = state.dirty ? "dirty" : "clean";
+      const branchLabel = state.branch || "detached";
+      let relation = "no-upstream";
+      if (state.aheadBehind) {
+        relation = `ahead ${state.aheadBehind.ahead}, behind ${state.aheadBehind.behind}`;
+      }
+      console.log(`  [git] ${name}: ${branchLabel}, ${dirtyLabel}, ${relation}`);
+      continue;
+    }
+
+    if (layer.source === "npm") {
+      const state = describeNpmLayerState(name, layerPath);
+      const installed = state.installedVersion || "unknown";
+      const published = state.publishedVersion || "unknown";
+      const relation = state.outdated ? "outdated" : "current-or-unknown";
+      console.log(`  [npm] ${name}: installed ${installed}, published ${published}, ${relation}`);
+      continue;
+    }
+
+    console.log(`  [unknown] ${name}: unsupported source ${layer.source || "unknown"}`);
+  }
+}
+
 function inferLayerPath(installDir, layerName) {
   const candidate = targetPathFor(installDir, layerName);
   return pathExists(candidate) ? candidate : null;
@@ -837,6 +1029,66 @@ function removeCommand(tokens) {
   console.log(`Updated ${manifestPath}`);
 }
 
+function diffCommand(tokens) {
+  const { installDir, target } = parseDiffArgs(tokens);
+  if (!target) {
+    throw new Error("Specify a layer to diff.");
+  }
+  if (!supportedSet.has(target)) {
+    throw new Error(`Unknown layer: ${target}`);
+  }
+  const { manifest } = loadManifestFromDir(installDir);
+  const layer = manifest.layers[target];
+  if (!layer) {
+    throw new Error(`Layer not recorded in manifest: ${target}`);
+  }
+  const layerPath = path.resolve(installDir, String(layer.path || ""));
+  if (!pathExists(layerPath)) {
+    throw new Error(`Layer path does not exist: ${layerPath}`);
+  }
+
+  if (layer.source === "git") {
+    ensureGitAvailable();
+    const summary = getGitDiffSummary(layerPath);
+    const aheadBehind = getGitAheadBehind(layerPath);
+    console.log(`architectonic diff ${target}`);
+    console.log(`  source: git`);
+    console.log(`  path: ${layerPath}`);
+    if (aheadBehind) {
+      console.log(`  upstream: ${aheadBehind.upstream}`);
+      console.log(`  ahead: ${aheadBehind.ahead}`);
+      console.log(`  behind: ${aheadBehind.behind}`);
+    }
+    if (!summary || !summary.lines.length) {
+      console.log(`  local changes: none`);
+      return;
+    }
+    console.log(`  local changes:`);
+    for (const line of summary.lines) {
+      console.log(`    ${line}`);
+    }
+    return;
+  }
+
+  if (layer.source === "npm") {
+    ensureNpmAvailable();
+    const state = describeNpmLayerState(target, layerPath);
+    console.log(`architectonic diff ${target}`);
+    console.log(`  source: npm`);
+    console.log(`  path: ${layerPath}`);
+    console.log(`  installed version: ${state.installedVersion || "unknown"}`);
+    console.log(`  published version: ${state.publishedVersion || "unknown"}`);
+    if (state.outdated) {
+      console.log(`  drift: newer package available`);
+    } else {
+      console.log(`  drift: none detected from package version`);
+    }
+    return;
+  }
+
+  throw new Error(`Unsupported source for diff: ${layer.source || "unknown"}`);
+}
+
 try {
   if (!command || command === "help" || command === "--help" || command === "-h") {
     printHelp();
@@ -863,6 +1115,16 @@ try {
     process.exit(0);
   }
 
+  if (command === "status") {
+    statusCommand(rest);
+    process.exit(0);
+  }
+
+  if (command === "diff") {
+    diffCommand(rest);
+    process.exit(0);
+  }
+
   if (command === "update") {
     updateCommand(rest);
     process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "architectonic",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "CLI for composing agentic system layers such as teleology, identity, project, and skills.",
   "license": "Apache-2.0",
   "type": "module",