deweyou-cli 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.1 - 2026-05-17
+
+### Fixed
+
+- publish cli as deweyou-cli package
+## 0.2.0 - 2026-05-17
+
+### Added
+
+- automate cli release changelog
+- colocate deweyou cli package
+
+### Changed
+
+- generate cli registry from assets
+All notable `deweyou-cli` package changes will be documented in this file.

package/README.md

@@ -0,0 +1,221 @@
+# deweyou-cli
+
+`deweyou-cli` bootstraps Dewey's personal agent workflows into any local
+repository. It manages the repo-level wiring for selected skills and rules while
+keeping the source assets in the central `deweyou/agents` hub.
+
+The v0 scope is intentionally small:
+
+- cache skills and rules from a local `deweyou/agents` checkout
+- initialize a repository with selected skills and rules
+- render the active agent context for the current repository
+- diagnose whether the current repository is wired correctly
+
+## Install
+
+From npm:
+
+```bash
+npm install -g deweyou-cli
+```
+
+During v0, point the CLI at your local `deweyou/agents` checkout before updating
+the cache:
+
+```bash
+export DEWEYOU_AGENTS_SOURCE=/path/to/deweyou/agents
+deweyou-cli agent update
+```
+
+## Quick Start
+
+```bash
+cd /path/to/your/repo
+deweyou-cli agent init
+deweyou-cli agent doctor
+deweyou-cli agent context --format markdown
+```
+
+For a non-interactive setup that selects everything:
+
+```bash
+deweyou-cli agent init --all --mode link --yes
+```
+
+## Mental Model
+
+`deweyou/agents` is the asset hub. It owns `skills/` and `rules/`.
+
+`deweyou-cli` is the workflow manager. It scans the hub assets, generates a
+cache registry under your home directory, then writes a small
+`.agents/manifest.json` into each repository so the repository knows which
+assets are active.
+
+Each repository chooses its own asset set. A coding repo can select coding
+skills and rules; a writing or design repo can select different ones.
+
+## Commands
+
+### `deweyou-cli agent update`
+
+Refreshes the local Dewey asset cache from `DEWEYOU_AGENTS_SOURCE`.
+
+```bash
+DEWEYOU_AGENTS_SOURCE=/path/to/deweyou/agents deweyou-cli agent update
+```
+
+This command writes the global cache at:
+
+```text
+~/.deweyou/agents/
+```
+
+Run this after changing or pulling updates in the asset hub.
+
+### `deweyou-cli agent init`
+
+Initializes the current repository with selected skills and rules.
+
+```bash
+deweyou-cli agent init
+```
+
+Without selection flags, this opens an interactive setup where you choose:
+
+- install mode
+- skills
+- rules
+
+Scripted examples:
+
+```bash
+deweyou-cli agent init --all --mode link --yes
+deweyou-cli agent init --skills code-knowledge,deweyou-design --rules code-style
+deweyou-cli agent init --dry-run
+```
+
+Flags:
+
+| Flag | Meaning |
+|------|---------|
+| `--all` | Select every skill and rule from the cached registry. |
+| `--skills a,b` | Select only the listed skill ids. Values are comma-separated. |
+| `--rules a,b` | Select only the listed rule ids. Values are comma-separated. |
+| `--mode link\|copy\|pointer` | Choose how the repository references selected assets. |
+| `--yes` | Run without prompts. Requires `--all`, `--skills`, or `--rules`. |
+| `--dry-run` | Print the planned files without writing them. |
+| `--force` | Replace existing Dewey-managed asset destinations when needed. |
+
+`--yes` does not guess a default asset set. It only confirms a scripted
+selection you already provided.
+
+### `deweyou-cli agent context`
+
+Prints the active Dewey agent context for the current repository.
+
+```bash
+deweyou-cli agent context --format markdown
+deweyou-cli agent context --format json
+```
+
+Formats:
+
+| Format | Meaning |
+|--------|---------|
+| `markdown` | Human-readable instructions and asset paths. This is the default. |
+| `json` | Structured context for tooling or future integrations. |
+
+The context output tells an agent which skills and rules are active, where their
+files live, whether the hub commit changed, and whether any selected asset hash
+changed in the local cache.
+
+### `deweyou-cli agent doctor`
+
+Checks whether the current repository and local cache are healthy.
+
+```bash
+deweyou-cli agent doctor
+```
+
+It verifies:
+
+- local cache registry exists and is valid
+- repository `.agents/manifest.json` exists and is valid
+- `AGENTS.md` exists
+- selected skills and rules still exist in the registry
+- selected asset hashes match the repository's initialized snapshot
+- selected asset files are present
+- symlinks are valid when using `link` mode
+
+The command exits with a non-zero status when a check fails.
+
+## Install Modes
+
+| Mode | Repository Writes | Best For |
+|------|-------------------|----------|
+| `link` | Symlinks selected assets into `.agents/skills/` and `.agents/rules/`. | Daily local work where updates should be immediately visible after cache refresh. |
+| `copy` | Copies selected assets into `.agents/skills/` and `.agents/rules/`. | Repositories that should keep a snapshot of the selected assets. |
+| `pointer` | Writes only `.agents/manifest.json` and `AGENTS.md`; assets stay in the global cache. | Minimal repo footprint and tooling that can follow absolute cache paths. |
+
+## Files Created
+
+Depending on the selected mode, `deweyou-cli agent init` may create or update:
+
+```text
+AGENTS.md
+.agents/manifest.json
+.agents/skills/<skill>/SKILL.md
+.agents/rules/<rule>.md
+```
+
+`AGENTS.md` receives a managed Dewey section that points agents at the selected
+workflow context. Existing content outside that managed section is preserved.
+
+## Safety Notes
+
+- Run `deweyou-cli agent update` before `deweyou-cli agent init`.
+- Asset ids must be kebab-case and must exist in the cached registry.
+- `--force` only replaces destinations that are already Dewey-managed. It
+  refuses to overwrite unrelated user-created files or directories.
+- `--dry-run` is the safest way to preview what `init` would write.
+- In v0, the asset source is local. Set `DEWEYOU_AGENTS_SOURCE` to the
+  `deweyou/agents` checkout you want to use.
+
+## Development
+
+The CLI source and tests are written in TypeScript. Vite+ builds the published
+JavaScript files into `dist/`.
+
+```bash
+npm run typecheck
+npm test
+npm run test:coverage
+npm run build
+npm pack --dry-run
+```
+
+## Release
+
+Merging CLI package changes into `main` runs the release workflow. It typechecks,
+runs tests, verifies the package with `npm pack --dry-run`, infers the next
+version from conventional commit messages, prepends [CHANGELOG.md](./CHANGELOG.md),
+tags `cli-vX.Y.Z`, and publishes `deweyou-cli` to npm.
+
+Release commit rules:
+
+- `feat:` creates a minor release.
+- `fix:`, `perf:`, and `refactor:` create a patch release.
+- `!` or `BREAKING CHANGE` creates a major release.
+- `docs:` entries are included in the changelog only when another releasable CLI
+  commit is present.
+- `test:` and `chore:` do not publish by themselves.
+
+## Relationship To `deweyou/agents`
+
+`deweyou/agents` continues to provide the actual skills, rules, and asset
+validation workflow. The CLI generates the cache registry during
+`deweyou-cli agent update`.
+
+`deweyou-cli` does not replace those assets. It gives every repository a
+repeatable way to choose and wire the assets it wants, without manually copying
+or linking the same files again and again.

package/dist/cache-CBEKVQeD.mjs

@@ -0,0 +1,231 @@
+import { cp, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { homedir } from "node:os";
+import { basename, dirname, join, relative } from "node:path";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import yaml from "js-yaml";
+//#region src/cli/registry.ts
+const { load: loadYaml } = yaml;
+async function loadRegistry(root) {
+	return { assets: {
+		skills: await scanSkills(root),
+		rules: await scanRules(root)
+	} };
+}
+async function scanSkills(root) {
+	const skillsDir = join(root, "skills");
+	const assets = {};
+	for (const entry of await safeReaddir(skillsDir)) {
+		if (!entry.isDirectory()) continue;
+		const skillPath = join(skillsDir, entry.name);
+		const frontmatter = await parseFrontmatter(join(skillPath, "SKILL.md"));
+		const name = frontmatter.name;
+		if (name !== entry.name) throw new Error(`skill ${entry.name} name must match frontmatter`);
+		assets[name] = {
+			path: toPosix(relative(root, skillPath)),
+			description: frontmatter.description,
+			hash: await hashDirectory(skillPath),
+			tags: frontmatter.tags
+		};
+	}
+	return sortObject(assets);
+}
+async function scanRules(root) {
+	const rulesDir = join(root, "rules");
+	const assets = {};
+	for (const entry of await safeReaddir(rulesDir)) {
+		if (!entry.isFile()) continue;
+		if (entry.name === "README.md") continue;
+		if (!entry.name.endsWith(".md")) continue;
+		const rulePath = join(rulesDir, entry.name);
+		const frontmatter = await parseFrontmatter(rulePath);
+		const expectedName = basename(entry.name, ".md");
+		const name = frontmatter.name;
+		if (name !== expectedName) throw new Error(`rule ${expectedName} name must match frontmatter`);
+		assets[name] = {
+			path: toPosix(relative(root, rulePath)),
+			description: frontmatter.description,
+			hash: await hashFile(rulePath),
+			tags: frontmatter.tags
+		};
+	}
+	return sortObject(assets);
+}
+async function parseFrontmatter(path) {
+	const match = (await readFile(path, "utf8")).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+	if (!match) throw new Error(`${path} must include YAML frontmatter`);
+	const frontmatter = loadYaml(match[1]);
+	if (!isPlainObject(frontmatter)) throw new Error(`${path} frontmatter must be an object`);
+	return {
+		name: requiredString(frontmatter.name, `${path} frontmatter name`),
+		description: requiredString(frontmatter.description, `${path} frontmatter description`),
+		tags: optionalTags(frontmatter.tags, `${path} frontmatter tags`)
+	};
+}
+function requiredString(value, label) {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${label} must be a non-empty string`);
+	return value;
+}
+function optionalTags(value, label) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+	return value.map((tag, index) => requiredString(tag, `${label}[${index}]`));
+}
+async function safeReaddir(path) {
+	try {
+		return await readdir(path, { withFileTypes: true });
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error)) throw error;
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+async function hashDirectory(dir) {
+	const files = await collectFiles(dir);
+	const hash = createHash("sha256");
+	for (const file of files) {
+		const relativePath = toPosix(relative(dir, file));
+		hash.update(relativePath);
+		hash.update("\0");
+		hash.update(await readFile(file));
+		hash.update("\0");
+	}
+	return `sha256:${hash.digest("hex")}`;
+}
+async function collectFiles(dir) {
+	const files = [];
+	for (const entry of await safeReaddir(dir)) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...await collectFiles(path));
+		else if (entry.isFile()) files.push(path);
+	}
+	return files.sort((a, b) => a.localeCompare(b));
+}
+async function hashFile(path) {
+	return `sha256:${createHash("sha256").update(await readFile(path)).digest("hex")}`;
+}
+function sortObject(object) {
+	return Object.fromEntries(Object.entries(object).sort(([a], [b]) => a.localeCompare(b)));
+}
+function toPosix(path) {
+	return path.split("\\").join("/");
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/cli/manifest.ts
+async function readJson(path, fallback) {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		if (!(error instanceof Error) || !("code" in error)) throw error;
+		if (error.code === "ENOENT" && arguments.length > 1) return fallback;
+		throw error;
+	}
+}
+async function writeJson(path, value) {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+//#endregion
+//#region src/cli/source.ts
+const DEFAULT_SOURCE = "deweyou/agents";
+function resolveSourceRoot({ env = process.env } = {}) {
+	if (env.DEWEYOU_AGENTS_SOURCE) return env.DEWEYOU_AGENTS_SOURCE;
+	throw new Error(`No local asset source configured. Set DEWEYOU_AGENTS_SOURCE to a checkout of ${DEFAULT_SOURCE}.`);
+}
+//#endregion
+//#region src/cli/cache.ts
+const CLI_VERSION = "0.1.0";
+const execFileAsync = promisify(execFile);
+function cachePaths({ homeDir = homedir() } = {}) {
+	const root = join(homeDir, ".deweyou", "agents");
+	return {
+		root,
+		assetsRoot: join(root, "assets"),
+		manifestPath: join(root, "manifest.json")
+	};
+}
+async function updateCache({ homeDir = homedir(), sourceRoot, cliVersion = CLI_VERSION } = {}) {
+	if (!sourceRoot) throw new Error("sourceRoot is required to update the Dewey assets cache");
+	const registry = await loadRegistry(sourceRoot);
+	const source = await resolveSourceSnapshot(sourceRoot);
+	const paths = cachePaths({ homeDir });
+	const tempAssetsRoot = join(paths.root, `assets.tmp-${process.pid}-${Date.now()}`);
+	try {
+		await mkdir(paths.root, { recursive: true });
+		await rm(tempAssetsRoot, {
+			recursive: true,
+			force: true
+		});
+		await mkdir(tempAssetsRoot, { recursive: true });
+		await writeJson(join(tempAssetsRoot, "registry.json"), registry);
+		await copyAssetDirectory(sourceRoot, tempAssetsRoot, "skills");
+		await copyAssetDirectory(sourceRoot, tempAssetsRoot, "rules");
+		await rm(paths.assetsRoot, {
+			recursive: true,
+			force: true
+		});
+		await rename(tempAssetsRoot, paths.assetsRoot);
+		const manifest = {
+			source,
+			cliVersion,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		await writeJson(paths.manifestPath, manifest);
+		return manifest;
+	} catch (error) {
+		await rm(tempAssetsRoot, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+async function runUpdate(flags = {}) {
+	const sourceRoot = flags.sourceRoot ?? resolveSourceRoot();
+	const manifest = await updateCache({
+		homeDir: flags.homeDir,
+		sourceRoot,
+		cliVersion: CLI_VERSION
+	});
+	const sourceLabel = manifest.source.commit ?? "local files";
+	console.log(`Updated Dewey agent assets from ${sourceLabel}`);
+	return manifest;
+}
+async function resolveSourceSnapshot(sourceRoot) {
+	return {
+		root: sourceRoot,
+		commit: await resolveGitCommit(sourceRoot)
+	};
+}
+async function resolveGitCommit(sourceRoot) {
+	try {
+		const { stdout } = await execFileAsync("git", [
+			"-C",
+			sourceRoot,
+			"rev-parse",
+			"HEAD"
+		]);
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+async function copyAssetDirectory(sourceRoot, assetsRoot, name) {
+	const source = join(sourceRoot, name);
+	try {
+		await stat(source);
+	} catch (error) {
+		/* v8 ignore next -- defensive guard for non-Node filesystem errors */
+		if (!(error instanceof Error) || !("code" in error)) throw error;
+		if (error.code === "ENOENT") return;
+		/* v8 ignore next -- stat() error variants are surfaced unchanged */
+		throw error;
+	}
+	await cp(source, join(assetsRoot, name), { recursive: true });
+}
+//#endregion
+export { cachePaths, writeJson as n, runUpdate, readJson as t };

package/dist/context-BYyhbv5D.mjs

@@ -0,0 +1,207 @@
+import { t as usageError } from "./deweyou.mjs";
+import { cachePaths, t as readJson } from "./cache-CBEKVQeD.mjs";
+import { readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+//#region src/cli/context.ts
+const MISSING_REPO_MANIFEST = "This repository has not been initialized. Run `deweyou-cli agent init`.";
+const MISSING_CACHE_REGISTRY = "Dewey asset cache is missing. Run `deweyou-cli agent update`.";
+const VALID_FORMATS = new Set(["markdown", "json"]);
+async function resolveContext({ repoRoot = process.cwd(), homeDir = homedir() } = {}) {
+	const manifest = await readJson(join(repoRoot, ".agents", "manifest.json"), null);
+	if (!manifest) return {
+		ok: false,
+		error: MISSING_REPO_MANIFEST
+	};
+	const paths = cachePaths({ homeDir });
+	const registry = await readRegistry(join(paths.assetsRoot, "registry.json"));
+	const cacheManifest = await readJson(paths.manifestPath, null);
+	if (!registry) return {
+		ok: false,
+		error: MISSING_CACHE_REGISTRY
+	};
+	const missing = findMissingAssets(manifest, registry);
+	if (missing.length > 0) return {
+		ok: false,
+		error: `Repository manifest references assets missing from the Dewey registry: ${missing.join(", ")}`
+	};
+	const context = {
+		ok: true,
+		repo: {
+			root: repoRoot,
+			mode: manifest.mode
+		},
+		runtime: {
+			sourceCommit: cacheManifest?.source?.commit ?? null,
+			repoSourceCommit: manifest.source?.commit ?? null
+		},
+		assets: {
+			skills: selectedAssets({
+				names: manifest.assets?.skills ?? [],
+				registryAssets: registry.assets?.skills ?? {},
+				manifestAssets: manifest.assetSnapshot?.skills ?? {},
+				useManifestMetadata: manifest.mode === "copy",
+				pathForAsset: (name, asset) => skillPath({
+					repoRoot,
+					manifest,
+					name,
+					asset
+				})
+			}),
+			rules: selectedAssets({
+				names: manifest.assets?.rules ?? [],
+				registryAssets: registry.assets?.rules ?? {},
+				manifestAssets: manifest.assetSnapshot?.rules ?? {},
+				useManifestMetadata: manifest.mode === "copy",
+				pathForAsset: (name, asset) => rulePath({
+					repoRoot,
+					manifest,
+					name,
+					asset
+				})
+			})
+		},
+		_notice: {
+			update: sourceNotice(cacheManifest, manifest),
+			assets: selectedAssetNotice(manifest, registry)
+		}
+	};
+	const missingPaths = await findMissingPaths(context);
+	if (missingPaths.length > 0) return {
+		ok: false,
+		error: `Selected Dewey asset paths are missing: ${missingPaths.join(", ")}`
+	};
+	return context;
+}
+function renderMarkdownContext(context) {
+	if (context.ok === false) return `# Dewey Agent Context
+
+${context.error}
+`;
+	return `# Dewey Agent Context
+
+## Required Protocol
+
+- Use the active skills and rules listed here for this repository.
+- Read only the referenced asset files when their instructions are needed.
+- Do not dump full skill or rule bodies into chat context.
+
+## Active Skills
+
+${renderAssets(context.assets.skills)}
+
+## Active Rules
+
+${renderAssets(context.assets.rules)}
+
+## Runtime Notices
+
+${renderNotices(context)}
+`;
+}
+async function runContext(flags = {}) {
+	const format = flags.format ?? "markdown";
+	if (!VALID_FORMATS.has(format)) throw usageError("format must be one of markdown or json");
+	const context = await resolveContext({
+		repoRoot: flags.repoRoot ?? process.cwd(),
+		homeDir: flags.homeDir ?? homedir()
+	});
+	if (format === "json") console.log(JSON.stringify(context, null, 2));
+	else console.log(renderMarkdownContext(context));
+	return context;
+}
+async function readRegistry(path) {
+	try {
+		const registry = JSON.parse(await readFile(path, "utf8"));
+		return {
+			...registry,
+			assets: {
+				skills: registry.assets?.skills ?? {},
+				rules: registry.assets?.rules ?? {}
+			}
+		};
+	} catch (error) {
+		/* v8 ignore next -- defensive guard for non-Node filesystem errors */
+		if (!(error instanceof Error) || !("code" in error)) throw error;
+		if (error.code === "ENOENT") return null;
+		/* v8 ignore next -- non-missing read errors should bubble to the caller */
+		throw error;
+	}
+}
+function findMissingAssets(manifest, registry) {
+	return [...(manifest.assets?.skills ?? []).filter((name) => !registry.assets.skills[name]).map((name) => `skill:${name}`), ...(manifest.assets?.rules ?? []).filter((name) => !registry.assets.rules[name]).map((name) => `rule:${name}`)];
+}
+function selectedAssets({ names, registryAssets, manifestAssets, useManifestMetadata, pathForAsset }) {
+	return names.map((name) => {
+		const asset = registryAssets[name];
+		const metadata = useManifestMetadata && manifestAssets[name] ? manifestAssets[name] : asset;
+		return {
+			name,
+			description: metadata.description,
+			hash: metadata.hash,
+			path: pathForAsset(name, asset)
+		};
+	});
+}
+function skillPath({ repoRoot, manifest, name, asset }) {
+	if (manifest.mode === "pointer") return join(manifest.cacheRoot, asset.path, "SKILL.md");
+	return join(repoRoot, ".agents", "skills", name, "SKILL.md");
+}
+function rulePath({ repoRoot, manifest, name, asset }) {
+	if (manifest.mode === "pointer") return join(manifest.cacheRoot, asset.path);
+	return join(repoRoot, ".agents", "rules", `${name}.md`);
+}
+function renderAssets(assets) {
+	if (assets.length === 0) return "- None selected.";
+	return assets.map((asset) => `- ${asset.name} - ${asset.description}\n  Hash: ${asset.hash}\n  Path: ${asset.path}`).join("\n");
+}
+function sourceNotice(cacheManifest, manifest) {
+	const current = cacheManifest?.source?.commit ?? null;
+	const initialized = manifest.source?.commit ?? null;
+	if (!current || !initialized || current === initialized) return null;
+	return `Dewey asset cache is at commit ${current}; this repo was initialized with ${initialized}. Run \`deweyou-cli agent init\` to refresh selected assets.`;
+}
+function selectedAssetNotice(manifest, registry) {
+	const changed = [...changedAssets({
+		prefix: "skill",
+		names: manifest.assets?.skills ?? [],
+		registryAssets: registry.assets?.skills ?? {},
+		manifestAssets: manifest.assetSnapshot?.skills ?? {}
+	}), ...changedAssets({
+		prefix: "rule",
+		names: manifest.assets?.rules ?? [],
+		registryAssets: registry.assets?.rules ?? {},
+		manifestAssets: manifest.assetSnapshot?.rules ?? {}
+	})];
+	if (changed.length === 0) return null;
+	return `Selected Dewey assets changed in cache: ${changed.join(", ")}. Run \`deweyou-cli agent init\` to refresh.`;
+}
+function changedAssets({ prefix, names, registryAssets, manifestAssets }) {
+	return names.filter((name) => {
+		const current = registryAssets[name]?.hash;
+		const initialized = manifestAssets[name]?.hash;
+		return Boolean(current && initialized && current !== initialized);
+	}).map((name) => `${prefix}:${name}`);
+}
+function renderNotices(context) {
+	const notices = [context._notice.update, context._notice.assets].filter(Boolean);
+	if (notices.length === 0) return "- None.";
+	return notices.map((notice) => `- ${notice}`).join("\n");
+}
+async function findMissingPaths(context) {
+	const paths = [...context.assets.skills.map((asset) => asset.path), ...context.assets.rules.map((asset) => asset.path)];
+	return (await Promise.all(paths.map(async (path) => {
+		try {
+			await stat(path);
+			return null;
+		} catch (error) {
+			/* v8 ignore next -- defensive guard for non-Node filesystem errors */
+			if (!(error instanceof Error) || !("code" in error)) throw error;
+			if (error.code === "ENOENT") return path;
+			/* v8 ignore next -- non-missing stat errors should bubble to the caller */
+			throw error;
+		}
+	}))).filter((path) => Boolean(path));
+}
+//#endregion
+export { runContext };