obsidian-lean-coder 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,7 +2,36 @@
 
 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` keeps `"private": true` — npm publishing is a separate explicitly approved action, never automatic.
+`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).
+The package-root entrypoint `dist/index.js` exported only `OLC_VERSION`, so npm loaders —
+which resolve the package root — never saw the plugin default export and ignored the package.
+`src/index.ts` now re-exports the plugin default alongside `OLC_VERSION`.
+Agents/skills still appear only via the project-local `.opencode` copy (by design, OLC-012).
+
+- **Verification:** typecheck clean, build OK, mock-ctx plugin load (`id=olc`, correct payload),
+  full suite 140/140 pass, real-loader test (`loading plugin`, zero `failed to load plugin`).
+- **Upgrade:** `npm install obsidian-lean-coder@0.1.1`, then list the package in `opencode.json`
+  `plugins` (see README §2).
 
 ## [0.1.0] — 2026-10-13 — MVP pre-release
 

package/README.md

@@ -1,6 +1,6 @@
 # OLC — Obsidian Lean Coder
 
-OpenCode extension for project-scoped planning, memory, and safe Git checkpoints. Work in progress — pre-release, not on npm.
+OpenCode extension for project-scoped planning, memory, and safe Git checkpoints. On npm as `obsidian-lean-coder` (v0.1.1 fixes plugin activation — see CHANGELOG).
 
 ## Three separate steps
 
@@ -9,7 +9,7 @@ Do not confuse these. They are different operations with different commands:
 | # | Step | What it does | Command |
 |---|------|--------------|---------|
 | 1 | **Dev install** | Install npm deps to hack on OLC itself | `npm ci && npm run build` |
-| 2 | **Plugin activation** | Load this checkout as an OpenCode plugin (local dev path) | config snippet below |
+| 2 | **Plugin activation** | Load OLC as an OpenCode plugin | `npm i obsidian-lean-coder` + `opencode.json` snippet below |
 | 3 | **Project init** | Register one app repo + vault with OLC (`initProject`, idempotent, create-only) | via the `olc-init` skill in OpenCode (the tested path) |
 
 ## 1. Dev install
@@ -26,11 +26,35 @@ npm run typecheck
 
 Expected: build clean, typecheck clean. `npm test` runs the full suite (currently 140 tests). `npm pack --dry-run` shows what would ship (`dist/`, `agents/`, `skills/`, `templates/`).
 
-> npm publish is blocked: `package.json` has `"private": true`. Removing that flag needs a separate explicit approval — never publish by accident.
+> Published on npm as `obsidian-lean-coder` (MIT). Republishing needs a separate explicit approval — never publish by accident.
 
-## 2. Plugin activation (local dev path)
+## 2. Plugin activation
 
-OLC is **not on npm**. Until a scoped name is reserved (DECISIONS.md #1), the only supported activation is the local-file path: an `index.js` under `.opencode/plugins/<name>/` auto-loads with no install step (proven in OLC-011, re-verified in OLC-071 against the packed tarball). The plugin entrypoint is `dist/plugin.js` (`src/plugin.ts` → `Plugin.define({ id: "olc" })`, one read-only `olc_status` tool, zero writes on load). Note `dist/index.js` only exports `OLC_VERSION` — it is not the plugin entrypoint.
+```sh
+npm install obsidian-lean-coder
+```
+
+Then list it in your project's `opencode.json` (npm loaders resolve the package root `dist/index.js`, which since v0.1.1 carries the plugin default export alongside `OLC_VERSION`):
+
+```json
+{
+  "plugins": ["obsidian-lean-coder"]
+}
+```
+
+Verify it loads (from the consuming project directory; the model call itself will fail without account funds, but plugin loading happens first):
+
+```sh
+OPENCODE_LOG_LEVEL=DEBUG opencode run --standalone "hi" --print-logs 2>&1 | grep -E "loading plugin.*obsidian-lean-coder|failed to load plugin"
+```
+
+Expected: a `loading plugin ... obsidian-lean-coder` line and **zero** `failed to load plugin` lines. (Verified 2026-10-13 via the equivalent local-file shape against the real loader; npm-registry install itself verified in OLC-071.)
+
+> `npm install` alone shows nothing in OpenCode — that is normal. The package must be listed under `plugins`, and agents/skills never auto-appear: they are project-local files you copy yourself (next step). No restart or rebuild needed after editing `opencode.json`.
+
+### Local dev path (this checkout, no npm)
+
+An `index.js` under `.opencode/plugins/<name>/` auto-loads with no install step (proven in OLC-011, re-verified in OLC-071). The plugin entrypoint is `dist/plugin.js` (`src/plugin.ts` → `Plugin.define({ id: "olc" })`, one read-only `olc_status` tool, zero writes on load).
 
 In your consuming project (replace `/home/you/olc` with your OLC checkout):
 
@@ -41,17 +65,19 @@ printf '%s\n' 'export { default } from "file://'"$PKG"'/dist/plugin.js";' > .ope
 printf '%s\n' '{ "type": "module", "dependencies": { "@opencode/plugin": "2.0.27" } }' > .opencode/plugins/olc/package.json
 ```
 
-Verify it loads (from the consuming project directory; the model call itself will fail without account funds, but plugin loading happens first):
+Verify with the same `grep` as above, expecting `.opencode/plugins/olc/index.js` in the loading line.
+
+Then install the agent/skill resources — recommended via the setup helper:
 
 ```sh
-OPENCODE_LOG_LEVEL=DEBUG opencode run --standalone "hi" --print-logs 2>&1 | grep -E "loading plugin.*plugins/olc|failed to load plugin"
+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
 ```
 
-Expected: a `loading plugin ... .opencode/plugins/olc/index.js` line and **zero** `failed to load plugin` lines.
-
-> Not supported (verified 2026-10-12, OLC-071): pointing `opencode.json` `plugins` (or `plugin`) at the package directory — bare path or `file://` URL — produced zero load attempts in this build, so there is nothing to verify there yet. npm-package activation is untestable until a name is reserved AND the entrypoint is wired (`dist/index.js` currently has no plugin default export; npm loaders resolve `dist/index.js`).
-
-Then place the agent/skill resources project-locally (DECISIONS.md #2 — programmatic registration was rejected for MVP):
+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
@@ -74,7 +100,7 @@ Supported versions: OpenCode 2.x with the V2 plugin API. OLC pins `@opencode/plu
 
 `initProject` (`src/init/index.ts`) registers one app repo + vault. It is idempotent and **create-only**: existing files are reported `preserved`, never overwritten. Anything needing a human choice comes back as `status: "needs-decision"` — no prompting inside the module.
 
-Run it via the `olc-init` skill inside OpenCode (recommended — the only tested path for MVP). A programmatic import is not yet wired: the package entrypoint (`dist/index.js`) currently exports only `OLC_VERSION`, and `initProject` lives in `src/init/index.ts` for internal/agent use.
+Run it via the `olc-init` skill inside OpenCode (recommended — the only tested path for MVP). A programmatic import is not yet wired: the package entrypoint (`dist/index.js`) exports `OLC_VERSION` plus the plugin default, and `initProject` lives in `src/init/index.ts` for internal/agent use.
 
 What it creates (only when missing):
 

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

@@ -1,5 +1,14 @@
 /**
  * OLC package entrypoint. Thin on purpose — see docs/PRD.md §8 for planned
  * module layout (config, core, git, logging, tools, validation).
+ *
+ * The plugin default export is re-exported here (not only from
+ * `./plugin.js`) because OpenCode's npm loader resolves the package root,
+ * i.e. `dist/index.js` — without a `default` export carrying `{ id, setup }`
+ * the loader ignores the package entirely (found by OLC-071 smoke test:
+ * zero load attempts for 0.1.0). `OLC_VERSION` is only consumed inside
+ * `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.0";
+export declare const OLC_VERSION = "0.2.0";
+export { default } from "./plugin.js";

package/dist/index.js

@@ -1,5 +1,14 @@
 /**
  * OLC package entrypoint. Thin on purpose — see docs/PRD.md §8 for planned
  * module layout (config, core, git, logging, tools, validation).
+ *
+ * The plugin default export is re-exported here (not only from
+ * `./plugin.js`) because OpenCode's npm loader resolves the package root,
+ * i.e. `dist/index.js` — without a `default` export carrying `{ id, setup }`
+ * the loader ignores the package entirely (found by OLC-071 smoke test:
+ * zero load attempts for 0.1.0). `OLC_VERSION` is only consumed inside
+ * `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.0";
+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.0",
+  "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"
   ],