obsidian-lean-coder 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to OLC (Obsidian Lean Coder) are recorded here.
 OLC is pre-release: versions are `0.x` until a controlled-testing release says otherwise.
 `package.json` shipped `"private": true` through 0.1.0; the flag was removed at publish time with explicit user approval, and 0.1.0 is live as [`obsidian-lean-coder`](https://www.npmjs.com/package/obsidian-lean-coder). Publishing a new version is still a separate explicitly approved action, never automatic.
 
+## [0.2.0] — 2026-10-13 — `olc-setup` resource installer
+
+New `olc-setup setup [--project|--global]` command (run manually via `npx obsidian-lean-coder setup`
+after install): copies the shipped agents/skills into OpenCode discovery paths —
+`<cwd>/.opencode` (project, default) or `~/.config/opencode` (`$XDG_CONFIG_HOME/opencode` when set,
+global; global use is allowed only for this plugin's own install). Missing directories are created;
+existing OLC agent/skill files are overwritten with the package versions (a deliberate, narrow
+exception to the create-only rule, scoped to the files this command owns — see README §2).
+`--dry-run` previews without writing; `opencode.json` is never edited (manual snippet printed after
+each run). Node builtins only, no runtime dependencies.
+
+- **Verification:** 6 fixture tests (`tests/setup.test.ts`: create, skip/overwrite, dry-run,
+  global scope, usage errors, mkdir -p); full suite 146/146 pass; typecheck/build clean.
+- **Upgrade:** `npm install obsidian-lean-coder@0.2.0`, then `npx obsidian-lean-coder setup`
+  (add `--global` for global scope).
+
 ## [0.1.1] — 2026-10-13 — plugin entrypoint fix
 
 Fixes npm-package activation (reported: `npm install` worked but nothing appeared in OpenCode).

package/README.md

@@ -67,7 +67,17 @@ printf '%s\n' '{ "type": "module", "dependencies": { "@opencode/plugin": "2.0.27
 
 Verify with the same `grep` as above, expecting `.opencode/plugins/olc/index.js` in the loading line.
 
-Then place the agent/skill resources project-locally (DECISIONS.md #2 — programmatic registration was rejected for MVP):
+Then install the agent/skill resources — recommended via the setup helper:
+
+```sh
+npx obsidian-lean-coder setup            # project scope: ./.opencode
+npx obsidian-lean-coder setup --global   # global scope: ~/.config/opencode
+npx obsidian-lean-coder setup --dry-run  # preview, writes nothing
+```
+
+Missing directories are created; existing OLC agent/skill files are overwritten with the package
+versions (a deliberate exception to the create-only rule, scoped to these files only).
+Manual equivalent (DECISIONS.md #2 — programmatic registration was rejected for MVP):
 
 ```sh
 PKG=/home/you/olc   # your OLC checkout

package/bin/olc-setup.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+/**
+ * OLC setup helper (OLC-075).
+ *
+ * Manually run after `npm install -g obsidian-lean-coder` (or npx):
+ *   olc-setup setup [--project|--global] [--dry-run]
+ *
+ * Copies the shipped agent/skill resources into OpenCode's discovery paths:
+ *   project scope (default): <cwd>/.opencode/{agents,skills}
+ *   global scope:            ~/.config/opencode/{agents,skills}
+ *                            ($XDG_CONFIG_HOME/opencode when set)
+ *
+ * Behavior (locked with the user):
+ * - Missing directories are created (mkdir -p).
+ * - Existing OLC agent/skill files are OVERWRITTEN with the package
+ *   versions. This is a deliberate, narrow exception to OLC's usual
+ *   create-only rule — and it applies ONLY to the files this command owns
+ *   (listed in OWNED_FILES below). Nothing else is touched.
+ * - `--dry-run` prints what would happen and writes nothing.
+ * - `opencode.json` is NEVER edited by this command. After it runs, it
+ *   prints the manual plugin-registration snippet for README §2.
+ *
+ * Node builtins only — no runtime dependencies.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+/** Files this command owns: [package-relative source, scope-relative dest]. */
+const OWNED_FILES = [
+  ["agents/olc-plan.md", ".opencode/agents/olc-plan.md"],
+  ["agents/olc-build.md", ".opencode/agents/olc-build.md"],
+  ["skills/olc-explore/SKILL.md", ".opencode/skills/olc-explore/SKILL.md"],
+];
+
+function usage() {
+  return [
+    "Usage: olc-setup setup [--project|--global] [--dry-run]",
+    "",
+    "  setup            copy shipped agents/skills into OpenCode discovery paths",
+    "  --project        install into <cwd>/.opencode (default)",
+    "  --global         install into ~/.config/opencode ($XDG_CONFIG_HOME/opencode when set)",
+    "  --dry-run        print what would happen, write nothing",
+    "",
+    "Existing OLC agent/skill files are overwritten with the package versions;",
+    "nothing else is touched, and opencode.json is never edited (see the",
+    "manual plugin-registration snippet printed after a successful run).",
+  ].join("\n");
+}
+
+function fail(message) {
+  process.stderr.write(`olc-setup: ${message}\n${usage()}\n`);
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  if (argv[0] !== "setup") fail(`expected subcommand \"setup\", got ${JSON.stringify(argv[0] ?? "(none)")}.`);
+  let scope = "project";
+  let dryRun = false;
+  for (const arg of argv.slice(1)) {
+    if (arg === "--project") scope = "project";
+    else if (arg === "--global") scope = "global";
+    else if (arg === "--dry-run") dryRun = true;
+    else fail(`unknown argument ${JSON.stringify(arg)}.`);
+  }
+  return { scope, dryRun };
+}
+
+function packageRoot() {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+function scopeRoot(scope) {
+  if (scope === "project") return resolve(process.cwd());
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return resolve(base, "opencode");
+}
+
+function main() {
+  const { scope, dryRun } = parseArgs(process.argv.slice(2));
+  const pkg = packageRoot();
+  const root = scopeRoot(scope);
+
+  const missing = OWNED_FILES.map(([src]) => src).filter((src) => !existsSync(join(pkg, src)));
+  if (missing.length > 0) {
+    process.stderr.write(
+      `olc-setup: installed package is incomplete, missing: ${missing.join(", ")}. Reinstall obsidian-lean-coder.\n`,
+    );
+    process.exit(1);
+  }
+
+  const summary = [];
+  for (const [src, destRel] of OWNED_FILES) {
+    const dest = join(root, destRel);
+    const wanted = readFileSync(join(pkg, src), "utf8");
+    const prior = existsSync(dest) ? readFileSync(dest, "utf8") : null;
+    if (prior === wanted) {
+      summary.push({ file: destRel, action: "skipped" });
+      continue;
+    }
+    if (!dryRun) {
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, wanted, "utf8");
+    }
+    summary.push({ file: destRel, action: prior === null ? "created" : "overwritten" });
+  }
+
+  const counts = { created: 0, overwritten: 0, skipped: 0 };
+  for (const entry of summary) {
+    counts[entry.action] += 1;
+    process.stdout.write(`${entry.action}  ${entry.file}\n`);
+  }
+  process.stdout.write(
+    `${dryRun ? "[dry-run] " : ""}done (${scope} scope, ${root}): ` +
+      `${counts.created} created, ${counts.overwritten} overwritten, ${counts.skipped} skipped.\n`,
+  );
+  if (!dryRun) {
+    process.stdout.write(
+      "\nNext (manual): register the plugin in opencode.json so OpenCode loads it:\n" +
+        '  { "plugins": ["obsidian-lean-coder"] }\n' +
+        "See README §2 for verification. opencode.json was left untouched.\n",
+    );
+  }
+}
+
+main();

package/dist/index.d.ts

@@ -10,5 +10,5 @@
  * `plugin.ts` tool `execute` (deferred to call time), so this re-export
  * cycle is safe under ESM live bindings.
  */
-export declare const OLC_VERSION = "0.1.1";
+export declare const OLC_VERSION = "0.2.0";
 export { default } from "./plugin.js";

package/dist/index.js

@@ -10,5 +10,5 @@
  * `plugin.ts` tool `execute` (deferred to call time), so this re-export
  * cycle is safe under ESM live bindings.
  */
-export const OLC_VERSION = "0.1.1";
+export const OLC_VERSION = "0.2.0";
 export { default } from "./plugin.js";

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "obsidian-lean-coder",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Obsidian Lean Coder — OpenCode extension for project-scoped planning, memory, and safe Git checkpoints.",
   "type": "module",
   "main": "./dist/index.js",
+  "bin": {
+    "olc-setup": "./bin/olc-setup.js"
+  },
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
@@ -16,6 +19,7 @@
     "agents",
     "skills",
     "templates",
+    "bin",
     "README.md",
     "CHANGELOG.md"
   ],