@wefter/opencode 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.3.0 - 2026-06-05
+
+- Added `.wefter/install-manifest.json` generation during `init` and a safe `wefter uninstall` command.
+- Added install manifest schema and documentation for previewing/removing Wefter-managed files.
+- Added roadmap and internal release specs for `delivery-implementation-migration` and `technical-shaping-foundation`.
+- Opted GitHub Actions workflows into Node 24 for JavaScript actions while preserving package test coverage across supported Node versions.
+
 ## 0.2.1 - 2026-06-04
 
 Stabilizes the `0.2.x` workflow contracts after the product-shaping release.

package/README.md

@@ -13,6 +13,7 @@ package: @wefter/opencode
 repo: wefter
 cli: wefter
 config: wefter.config.json
+install manifest: .wefter/install-manifest.json
 local workflow files: .wefter/
 runtime artifacts: .audit/wefter/ for legacy workflows; .wefter/runs/ for product-shaping
 ```
@@ -68,6 +69,7 @@ wefter docs audit --profile-path docs/audits/lenses.json --passes-per-lens 1 --m
 wefter profile import --source docs/audits/lenses.json --force
 wefter docs repair --audit-report .audit/wefter/documentation-audit/<run-id>/final/final-documentation-audit-report.md
 wefter new-run documentation-audit --passes-per-lens 1 --max-audits 12
+wefter uninstall --dry-run
 ```
 
 ## Default Config
@@ -110,6 +112,7 @@ wefter new-run documentation-audit --passes-per-lens 1 --max-audits 12
 - `docs audit --profile-path` can use a repository-specific audit profile for one run without changing `wefter.config.json`.
 - `profile import` validates and copies an existing repository-relative audit profile into the configured Wefter profile path.
 - `docs repair` writes through a staging directory and requires an existing repository-relative audit report path.
+- `init` writes `.wefter/install-manifest.json` with checksums for installed files; `uninstall` removes only unchanged manifest-recorded files unless `--force` is used.
 - Paths in `wefter.config.json` must be relative to the target repository and must not contain `..`.
 - Run names are plain directory names and cannot contain path separators.
 - `product-shaping` writes versioned product specs under `.wefter/specs/` and runtime runs under `.wefter/runs/product-shaping/` by default.
@@ -119,8 +122,7 @@ wefter new-run documentation-audit --passes-per-lens 1 --max-audits 12
 
 ## Product Direction
 
-Next hardening steps after the `0.2.1` stabilization release:
+Next hardening steps after the `0.3.0` install-manifest release:
 
-1. Add installation manifest/uninstall support.
-2. Continue migration from legacy `work-unit-implementation` naming toward `delivery-implementation`.
-3. Implement `technical-shaping` only after its contract, CLI behavior and OpenCode command are ready.
+1. Continue migration from legacy `work-unit-implementation` naming toward `delivery-implementation`.
+2. Implement `technical-shaping` only after its contract, CLI behavior and OpenCode command are ready.

package/docs/INSTALLATION.md

@@ -28,6 +28,15 @@ Validate an installation with:
 wefter doctor
 ```
 
+Preview and remove an installation with:
+
+```bash
+wefter uninstall --dry-run
+wefter uninstall --yes
+```
+
+`uninstall` uses `.wefter/install-manifest.json` and removes only unchanged Wefter-managed files unless `--force` is used. It also removes Wefter commands and watcher ignores from `opencode.json` without deleting unrelated user configuration.
+
 Import an existing repository-specific documentation audit profile, such as a legacy `docs/audits/lenses.json`, with:
 
 ```bash

package/docs/ROADMAP.md

@@ -0,0 +1,48 @@
+# Roadmap
+
+Wefter development should move in small workflow releases. Each release must preserve installed-project compatibility unless a migration path is explicit.
+
+## Current Foundation
+
+- `product-shaping` is available and produces `DELIVERABLES.md` as the product handoff.
+- `work-unit-implementation` remains the executable implementation engine under legacy vocabulary.
+- `technical-shaping` is registered as planned metadata only; it must not install commands until implemented.
+- `init` records installed files in `.wefter/install-manifest.json`; `uninstall` removes manifest-recorded files safely.
+
+## Next Release Order
+
+1. `delivery-implementation-migration`
+2. `technical-shaping-foundation`
+3. CLI modularization and schema validation hardening
+
+## Delivery Implementation Migration
+
+Goal: migrate vocabulary and defaults from `work-unit-implementation` toward `delivery-implementation` without breaking existing installations.
+
+Required decisions:
+
+- Whether `DELIVERABLES.md` becomes the default implementation source document.
+- Which legacy command aliases remain and for how long.
+- Whether schemas are renamed, aliased or versioned in place.
+- How OpenCode agent names transition without invalidating existing configs.
+
+Non-goals:
+
+- Do not remove `work-unit` commands in the first migration release.
+- Do not change product-shaping responsibilities.
+- Do not create technical design artifacts in delivery implementation.
+
+## Technical Shaping Foundation
+
+Goal: define a workflow between product-shaped deliverables and delivery implementation.
+
+Required outputs:
+
+- Technical decisions and constraints.
+- Data contracts and interface expectations.
+- Verification strategy for delivery implementation.
+- Explicit human gates for architecture, security, persistence and migration decisions.
+
+Activation rule:
+
+`technical-shaping` commands stay in `plannedCommands` until the workflow has process docs, config/profile defaults, prompt templates, agents, schemas, CLI run generation and validation tests.

package/docs/SAFETY_MODEL.md

@@ -11,6 +11,7 @@ Core rules:
 - Versioned workflow configuration is written under `.wefter/` by default.
 - Paths are target-repository relative and must not contain `..`.
 - Run directories are staged before becoming visible as final runs.
+- Installations write `.wefter/install-manifest.json`; uninstall removes manifest-recorded files only when unchanged unless `--force` is explicit.
 - OpenCode agent permissions restrict write access to configured artifact paths.
 - Implementation work must be task-level, reviewed and validated before moving to the next work unit.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wefter/opencode",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Installable Wefter workflows for OpenCode projects.",
   "type": "module",
   "repository": {

package/schemas/install-manifest.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wefter.dev/schemas/install-manifest.schema.json",
+  "type": "object",
+  "required": ["version", "packageName", "packageVersion", "generatedAt", "files", "managedOpencode"],
+  "properties": {
+    "version": { "const": 1 },
+    "packageName": { "const": "@wefter/opencode" },
+    "packageVersion": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "sha256"],
+        "properties": {
+          "path": { "$ref": "#/$defs/relativePath" },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        },
+        "additionalProperties": false
+      }
+    },
+    "managedOpencode": {
+      "type": "object",
+      "required": ["commands", "skillsPath", "watcherIgnores"],
+      "properties": {
+        "commands": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "skillsPath": { "$ref": "#/$defs/relativePath" },
+        "watcherIgnores": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "relativePath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?![A-Za-z]:)(?![\\\\/])(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))[^\r\n]+$"
+    }
+  }
+}

package/src/cli/main.js

@@ -1,12 +1,14 @@
 import fs from "node:fs";
+import crypto from "node:crypto";
 import path from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath } from "node:url";
 
-const VERSION = "0.2.1";
+const VERSION = "0.3.0";
 const CONFIG_FILE = "wefter.config.json";
+const INSTALL_MANIFEST_FILE = ".wefter/install-manifest.json";
 const PRODUCT_SHAPING_WORKFLOW_ID = "product-shaping";
 const DOCUMENTATION_REPAIR_WORKFLOW_ID = "documentation-repair";
 const WORK_UNIT_WORKFLOW_ID = "work-unit-implementation";
@@ -67,6 +69,7 @@ function printHelp() {
 
 Usage:
   wefter init [--yes] [--force] [--target <path>] [--profile-path <path>] [--artifact-root <path>] [--template-root <path>] [--process-doc-path <path>] [--runner-command <command>]
+  wefter uninstall [--target <path>] [--yes] [--force] [--dry-run]
   wefter product shape [--target <path>] [--release-id <id>] [--run-name <name>] [--spec-root <path>] [--run-root <path>] [--config-path <path>] [--profile-path <path>] [--dry-run]
   wefter product validate [--target <path>] [--release-id <id>] [--run-id <id> | --run-root <path>] [--config-path <path>] [--json]
   wefter docs audit [--target <path>] [--profile-path <path>] [--run-name <name>] [--passes-per-lens <n>] [--max-audits <n>] [--dry-run]
@@ -80,6 +83,7 @@ Usage:
 
 Commands:
   init              Install opencode agents, skill, commands, templates and local config.
+  uninstall         Remove files recorded in the Wefter install manifest.
   product shape     Generate one product-shaping run skeleton.
   product validate  Validate product-shaping specs against the completion gate.
   docs audit        Generate one documentation audit run from the configured profile.
@@ -125,6 +129,9 @@ function allowedFlagsForCommand(command, subcommand) {
   if (command === "init") {
     return ["yes", "force", "target", "profile-path", "artifact-root", "template-root", "process-doc-path", "runner-command"];
   }
+  if (command === "uninstall") {
+    return ["target", "yes", "force", "dry-run"];
+  }
   if (command === "new-run") {
     return ["target", "profile-path", "run-name", "passes-per-lens", "max-audits", "dry-run"];
   }
@@ -398,6 +405,129 @@ function writeJson(filePath, value) {
   fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 
+function sha256File(filePath) {
+  return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+
+function listFilesRecursive(root) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const files = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const fullPath = path.join(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listFilesRecursive(fullPath));
+      continue;
+    }
+    if (entry.isFile()) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+function addFileIfExists(targetRoot, files, fullPath) {
+  if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
+    return;
+  }
+  ensureInside(targetRoot, fullPath, "installed file");
+  files.add(toDisplayPath(targetRoot, fullPath));
+}
+
+function addDirectoryFilesIfExists(targetRoot, files, fullPath) {
+  if (!fs.existsSync(fullPath)) {
+    return;
+  }
+  ensureInside(targetRoot, fullPath, "installed directory");
+  for (const file of listFilesRecursive(fullPath)) {
+    addFileIfExists(targetRoot, files, file);
+  }
+}
+
+function knownOpencodeCommandNames() {
+  return [
+    "wefter-audit-docs",
+    "wefter-generate-doc-audit-profile",
+    "wefter-repair-docs",
+    "wefter-shape-product",
+    "wefter-run-work-unit"
+  ];
+}
+
+function configuredWatcherIgnores(targetRoot, config) {
+  const workUnitConfig = readJsonIfExists(path.join(targetRoot, workUnitConfigPath(config)), "work-unit config");
+  const productSettings = workflowSettings(config, PRODUCT_SHAPING_WORKFLOW_ID);
+  return [config.artifactRoot, config.templateRoot, documentationRepairArtifactRoot(), workUnitConfig?.runArtifactsRoot, productSettings.enabled ? productShapingRunRoot(config) : null]
+    .filter(Boolean)
+    .map((ignored) => `${ignored.replace(/\/$/, "")}/**`);
+}
+
+function collectInstallManifestFiles(targetRoot, config) {
+  const files = new Set();
+  addFileIfExists(targetRoot, files, path.join(targetRoot, CONFIG_FILE));
+  addDirectoryFilesIfExists(targetRoot, files, path.join(targetRoot, config.workflowRoot));
+  addDirectoryFilesIfExists(targetRoot, files, path.join(targetRoot, config.templateRoot));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, config.profilePath));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, config.processDocPath));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, productShapingConfigPath(config)));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, productShapingProfilePath(config)));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, workUnitConfigPath(config)));
+  addFileIfExists(targetRoot, files, path.join(targetRoot, workUnitProfilePath(config)));
+
+  const opencodeAgentRoot = path.join(targetRoot, ".opencode/agent");
+  if (fs.existsSync(opencodeAgentRoot)) {
+    for (const file of fs.readdirSync(opencodeAgentRoot)) {
+      if (file.startsWith("wefter-") && file.endsWith(".md")) {
+        addFileIfExists(targetRoot, files, path.join(opencodeAgentRoot, file));
+      }
+    }
+  }
+  for (const skill of ["documentation-audit", "documentation-repair", "product-shaping", "work-unit-implementation"]) {
+    addDirectoryFilesIfExists(targetRoot, files, path.join(targetRoot, ".opencode/skills", skill));
+  }
+
+  return [...files]
+    .filter((relativePath) => relativePath !== INSTALL_MANIFEST_FILE && relativePath !== "opencode.json")
+    .sort();
+}
+
+function writeInstallManifest(targetRoot, config) {
+  const manifestPath = path.join(targetRoot, INSTALL_MANIFEST_FILE);
+  const files = collectInstallManifestFiles(targetRoot, config).map((relativePath) => ({
+    path: relativePath,
+    sha256: sha256File(path.join(targetRoot, relativePath))
+  }));
+  writeJson(manifestPath, {
+    version: 1,
+    packageName: "@wefter/opencode",
+    packageVersion: VERSION,
+    generatedAt: new Date().toISOString(),
+    files,
+    managedOpencode: {
+      commands: knownOpencodeCommandNames(),
+      skillsPath: ".opencode/skills",
+      watcherIgnores: configuredWatcherIgnores(targetRoot, config)
+    }
+  });
+}
+
+function removeEmptyParents(targetRoot, startDir) {
+  let current = startDir;
+  while (current && current !== targetRoot && isInsideDirectory(targetRoot, current)) {
+    if (!fs.existsSync(current)) {
+      current = path.dirname(current);
+      continue;
+    }
+    const entries = fs.readdirSync(current);
+    if (entries.length > 0) {
+      return;
+    }
+    fs.rmdirSync(current);
+    current = path.dirname(current);
+  }
+}
+
 function writeTextIfSafe(filePath, content, force) {
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   if (fs.existsSync(filePath)) {
@@ -570,17 +700,12 @@ function copyDirectory(sourceRoot, destinationRoot, force) {
 function mergeOpencodeConfig(targetRoot, config, force) {
   const opencodePath = path.join(targetRoot, "opencode.json");
   const existing = fs.existsSync(opencodePath) ? readJson(opencodePath, "opencode.json") : { "$schema": "https://opencode.ai/config.json" };
-  const workUnitConfig = readJsonIfExists(path.join(targetRoot, workUnitConfigPath(config)), "work-unit config");
   const productSettings = workflowSettings(config, PRODUCT_SHAPING_WORKFLOW_ID);
 
   existing["$schema"] = existing["$schema"] || "https://opencode.ai/config.json";
   existing.watcher = existing.watcher || {};
   existing.watcher.ignore = Array.isArray(existing.watcher.ignore) ? existing.watcher.ignore : [];
-  for (const ignored of [config.artifactRoot, config.templateRoot, documentationRepairArtifactRoot(), workUnitConfig?.runArtifactsRoot, productSettings.enabled ? productShapingRunRoot(config) : null]) {
-    if (!ignored) {
-      continue;
-    }
-    const pattern = `${ignored.replace(/\/$/, "")}/**`;
+  for (const pattern of configuredWatcherIgnores(targetRoot, config)) {
     if (!existing.watcher.ignore.includes(pattern)) {
       existing.watcher.ignore.push(pattern);
     }
@@ -1040,6 +1165,7 @@ async function commandInit(flags) {
   if (!fs.existsSync(profileFullPath)) {
     writeJson(profileFullPath, defaultProfile(config));
   }
+  writeInstallManifest(targetRoot, config);
 
   console.log(`Installed Wefter for OpenCode into ${targetRoot}`);
   console.log(`Profile: ${config.profilePath}`);
@@ -1049,6 +1175,122 @@ async function commandInit(flags) {
   console.log("Restart opencode before using /wefter-shape-product, /wefter-audit-docs, /wefter-generate-doc-audit-profile, /wefter-repair-docs, or /wefter-run-work-unit.");
 }
 
+function readInstallManifest(targetRoot) {
+  const manifestPath = path.join(targetRoot, INSTALL_MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`Missing ${INSTALL_MANIFEST_FILE}. Re-run wefter init with the current version before uninstalling, or remove Wefter files manually.`);
+  }
+  const manifest = readJson(manifestPath, "install manifest");
+  assertObject(manifest, "Install manifest");
+  if (manifest.version !== 1) {
+    throw new Error("Install manifest must have version: 1.");
+  }
+  if (!Array.isArray(manifest.files)) {
+    throw new Error("Install manifest files must be an array.");
+  }
+  return manifest;
+}
+
+function updateOpencodeForUninstall(targetRoot, manifest, dryRun) {
+  const opencodePath = path.join(targetRoot, "opencode.json");
+  if (!fs.existsSync(opencodePath)) {
+    return false;
+  }
+  const opencode = readJson(opencodePath, "opencode.json");
+  let changed = false;
+  for (const commandName of manifest.managedOpencode?.commands || knownOpencodeCommandNames()) {
+    if (opencode.command?.[commandName]) {
+      delete opencode.command[commandName];
+      changed = true;
+    }
+  }
+  const watcherIgnore = opencode.watcher?.ignore;
+  if (Array.isArray(watcherIgnore)) {
+    const remove = new Set(manifest.managedOpencode?.watcherIgnores || []);
+    const nextIgnore = watcherIgnore.filter((item) => !remove.has(item));
+    if (nextIgnore.length !== watcherIgnore.length) {
+      opencode.watcher.ignore = nextIgnore;
+      changed = true;
+    }
+  }
+  const skillsPath = manifest.managedOpencode?.skillsPath || ".opencode/skills";
+  if (Array.isArray(opencode.skills?.paths) && opencode.skills.paths.includes(skillsPath)) {
+    const skillsRoot = path.join(targetRoot, skillsPath);
+    const hasRemainingSkills = fs.existsSync(skillsRoot) && listFilesRecursive(skillsRoot).length > 0;
+    if (!hasRemainingSkills) {
+      opencode.skills.paths = opencode.skills.paths.filter((item) => item !== skillsPath);
+      changed = true;
+    }
+  }
+  if (changed && !dryRun) {
+    writeJson(opencodePath, opencode);
+  }
+  return changed;
+}
+
+async function confirmUninstall(flags, targetRoot, manifest) {
+  if (flags.yes || flags["dry-run"] || !process.stdin.isTTY) {
+    return;
+  }
+  const rl = readline.createInterface({ input, output });
+  const answer = await rl.question(`Remove ${manifest.files.length} Wefter-managed files from ${targetRoot}? Type 'yes' to continue: `);
+  rl.close();
+  if (answer.trim().toLowerCase() !== "yes") {
+    throw new Error("Uninstall cancelled.");
+  }
+}
+
+async function commandUninstall(flags) {
+  const targetRoot = resolveTarget(flags);
+  const manifest = readInstallManifest(targetRoot);
+  await confirmUninstall(flags, targetRoot, manifest);
+
+  const removed = [];
+  const skipped = [];
+  let skippedModified = false;
+  for (const item of [...manifest.files].sort((a, b) => b.path.length - a.path.length)) {
+    const relativePath = normalizeRelativePath(item.path, "install manifest file path");
+    const fullPath = path.join(targetRoot, relativePath);
+    ensureInside(targetRoot, fullPath, "install manifest file");
+    if (!fs.existsSync(fullPath)) {
+      skipped.push(`${relativePath} (missing)`);
+      continue;
+    }
+    const currentHash = sha256File(fullPath);
+    if (currentHash !== item.sha256 && !flags.force) {
+      skipped.push(`${relativePath} (modified; use --force to remove)`);
+      skippedModified = true;
+      continue;
+    }
+    if (!flags["dry-run"]) {
+      fs.unlinkSync(fullPath);
+      removeEmptyParents(targetRoot, path.dirname(fullPath));
+    }
+    removed.push(relativePath);
+  }
+
+  const opencodeChanged = updateOpencodeForUninstall(targetRoot, manifest, flags["dry-run"]);
+  const manifestPath = path.join(targetRoot, INSTALL_MANIFEST_FILE);
+  if (fs.existsSync(manifestPath) && !flags["dry-run"] && !skippedModified) {
+    fs.unlinkSync(manifestPath);
+    removeEmptyParents(targetRoot, path.dirname(manifestPath));
+  }
+
+  console.log(`${flags["dry-run"] ? "Would remove" : "Removed"} Wefter-managed files: ${removed.length}`);
+  if (skipped.length > 0) {
+    console.log(`Skipped files: ${skipped.length}`);
+    for (const item of skipped) {
+      console.log(`- ${item}`);
+    }
+  }
+  if (opencodeChanged) {
+    console.log(`${flags["dry-run"] ? "Would update" : "Updated"} opencode.json Wefter entries.`);
+  }
+  if (skippedModified && !flags["dry-run"]) {
+    console.log(`Kept ${INSTALL_MANIFEST_FILE} so skipped files can be reviewed or removed with --force.`);
+  }
+}
+
 function readTextRequired(filePath) {
   if (!fs.existsSync(filePath)) {
     throw new Error(`Missing ${filePath}`);
@@ -2603,12 +2845,7 @@ function commandDoctor(flags) {
       throw new Error("Missing .opencode/skills in opencode skills.paths.");
     }
     const watcherIgnore = Array.isArray(opencode.watcher?.ignore) ? opencode.watcher.ignore : [];
-    const workUnitConfig = readJson(path.join(targetRoot, workUnitConfigPath(config)), "work-unit config");
-    for (const ignored of [config.artifactRoot, config.templateRoot, documentationRepairArtifactRoot(), workUnitConfig.runArtifactsRoot, productSettings.enabled ? productShapingRunRoot(config) : null]) {
-      if (!ignored) {
-        continue;
-      }
-      const pattern = `${ignored.replace(/\/$/, "")}/**`;
+    for (const pattern of configuredWatcherIgnores(targetRoot, config)) {
       if (!watcherIgnore.includes(pattern)) {
         throw new Error(`Missing opencode watcher ignore '${pattern}'.`);
       }
@@ -2648,6 +2885,10 @@ export async function main(argv = process.argv.slice(2)) {
     await commandInit(flags);
     return;
   }
+  if (command === "uninstall") {
+    await commandUninstall(flags);
+    return;
+  }
   if (command === "new-run") {
     if (subcommand && subcommand !== "documentation-audit") {
       throw new Error(`Unsupported workflow for new-run: ${subcommand}`);