@first-tree-ai/context-tree 0.1.8 → 0.1.9-alpha.202609020917

package/README.md

@@ -104,9 +104,9 @@ An identical connection is idempotent. An explicit connect automatically
 switches the project. GitHub checkouts use the repository's lowercase name in
 the same flat managed namespace as created trees.
 
-`context-tree list` reports valid, clean managed trees as
-`{ schemaVersion: 1, trees: [{ name, tree }] }`; a missing managed directory
-is an empty list.
+`context-tree list` reports valid, clean managed trees; `context-tree list --json`
+returns them as `{ schemaVersion: 1, trees: [{ name, tree }] }`, and a missing
+managed directory is an empty list.
 
 ### Read
 
@@ -190,7 +190,21 @@ orchestrates the five concrete workflows. `install` is the distribution
 entry point, run for you by `npm install`. `resolve`, `sync`, `prepare-write`,
 `finish-write`, and `verify` are plumbing or diagnostic commands rather than
 separate user intentions; `list` backs setup's connect-target discovery.
-All machine-readable responses use strict schema version `1`.
+
+### Output
+
+`create`, `connect`, `list`, `resolve`, `publish`, `read`, and `verify` print
+human-readable text by default and accept `--json` to emit their strict schema
+version `1` payload for scripts and agents; in text mode a failure prints a
+sanitized message to stderr with a non-zero exit code. The six skills always
+pass `--json`. `sync`, `prepare-write`, `finish-write`, and `install` are
+low-level plumbing and always emit that JSON (with the error envelope on stdout).
+`--help` and `--version` are always plain text.
+
+```bash
+context-tree verify                 # human-readable report
+context-tree verify --json          # { "ok": true, "schemaVersion": 1, ... }
+```
 
 `verify` is intended for CI and diagnostics. Normal skills invoke it only after
 an operation reports invalid tree content.

package/dist/cli/index.mjs

@@ -26460,46 +26460,139 @@ function reclaimAbandonedWrites(root, checkoutBranch, runner) {
 	}
 }
 //#endregion
+//#region src/cli/format.ts
+const POINTER_NOTE = {
+	skipped: "left unchanged",
+	updated: "updated",
+	written: "written"
+};
+function treeLines(tree, indent = "  ") {
+	const lines = [`${indent}Path:       ${tree.path}`];
+	if (tree.kind === "github") lines.push(`${indent}Repository: ${tree.repository}`);
+	return lines;
+}
+function formatCreate(result) {
+	return [
+		`${result.created ? "Created" : "Reused"} managed Context Tree "${result.title}".`,
+		`  Path:     ${result.treePath}`,
+		`  Branch:   ${result.branch}`,
+		`  Commit:   ${result.commitSha}`,
+		`  AGENTS.md: ${POINTER_NOTE[result.pointer]}`
+	].join("\n");
+}
+function formatConnect(result) {
+	return [
+		`Connected ${result.tree.kind} Context Tree.`,
+		...treeLines(result.tree),
+		`  AGENTS.md:  ${POINTER_NOTE[result.pointer]}`
+	].join("\n");
+}
+function formatResolve(result) {
+	return [`Connected ${result.tree.kind} Context Tree.`, ...treeLines(result.tree)].join("\n");
+}
+function formatList(result) {
+	if (result.trees.length === 0) return "No managed Context Trees.";
+	const count = result.trees.length;
+	const lines = [`${count} managed Context Tree${count === 1 ? "" : "s"}:`];
+	for (const entry of result.trees) lines.push(`  ${entry.name}  ${entry.tree.kind}  ${entry.tree.path}`);
+	return lines.join("\n");
+}
+function formatPublish(result) {
+	return [
+		`Published Context Tree to ${result.repository}.`,
+		`  URL:    ${result.url}`,
+		`  Branch: ${result.branch}`,
+		`  Commit: ${result.sha}`
+	].join("\n");
+}
+function formatRead(result) {
+	const title = result.node.frontmatter.title;
+	const lines = [];
+	if (typeof title === "string" && title.trim().length > 0) lines.push(title.trim());
+	lines.push(`Path: ${result.node.path} (${result.node.kind}, ${result.node.contentClass})`);
+	lines.push(`Root: ${result.root}`);
+	if (result.node.body.trim().length > 0) lines.push("", result.node.body.trimEnd());
+	if (result.children.length > 0) {
+		lines.push("", "Children:");
+		for (const child of result.children) {
+			const description = child.description ? ` — ${child.description}` : "";
+			lines.push(`  ${child.title}${description}  [${child.path}]`);
+		}
+	}
+	return lines.join("\n");
+}
+function formatVerify(report) {
+	const counts = report.scannedByContentClass;
+	const lines = [
+		report.ok ? "Context Tree OK." : "Context Tree INVALID.",
+		`  Root:    ${report.root}`,
+		`  Scanned: normal=${counts.normal} member=${counts.member} repo-infra=${counts["repo-infra"]}`
+	];
+	if (report.findings.length > 0) {
+		lines.push("  Findings:");
+		for (const finding of report.findings) lines.push(`    ${finding.code} ${finding.path}: ${finding.message}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
 //#region src/cli/api.ts
 const defaultIo = {
 	cwd: () => process.cwd(),
+	stderr: (value) => process.stderr.write(value),
 	stdout: (value) => process.stdout.write(value)
 };
+/** Commands that default to human-readable text and accept --json to restore JSON. */
+const TEXT_DEFAULT_COMMANDS = new Set([
+	"create",
+	"connect",
+	"list",
+	"resolve",
+	"publish",
+	"read",
+	"verify"
+]);
 function line(io, value) {
 	io.stdout(`${value}\n`);
 }
+function errline(io, value) {
+	(io.stderr ?? ((text) => process.stderr.write(text)))(`${value}\n`);
+}
+function emit(io, json, result, format) {
+	line(io, json ? JSON.stringify(result) : format(result));
+}
+const jsonOption = ["--json", "print machine-readable JSON (schema version 1) instead of text"];
 function createContextTreeCli(io = defaultIo) {
 	const program = new Command().name("context-tree").description("Create, connect, list, read, write, and publish Context Trees.").addHelpCommand(false).version(readPackageVersion()).exitOverride().configureOutput({
 		writeErr: () => void 0,
 		writeOut: io.stdout
 	});
-	program.command("create").description("Create and connect one uniquely named managed Context Tree for the current project.").option("--project-path <path>", "project directory", ".").action((options) => {
-		line(io, JSON.stringify(createProject(resolve(io.cwd(), options.projectPath))));
+	program.command("create").description("Create and connect one uniquely named managed Context Tree for the current project.").option("--project-path <path>", "project directory", ".").option(...jsonOption).action((options) => {
+		emit(io, options.json, createProject(resolve(io.cwd(), options.projectPath)), formatCreate);
 	});
-	program.command("connect").description("Connect the project by managed tree name, GitHub OWNER/REPO, or exact disk path.").argument("[name-or-repository]", "managed tree name or GitHub OWNER/REPO").option("--project-path <path>", "project directory", ".").option("--tree-path <path>", "exact Context Tree Git root to connect in place").action((target, options) => {
+	program.command("connect").description("Connect the project by managed tree name, GitHub OWNER/REPO, or exact disk path.").argument("[name-or-repository]", "managed tree name or GitHub OWNER/REPO").option("--project-path <path>", "project directory", ".").option("--tree-path <path>", "exact Context Tree Git root to connect in place").option(...jsonOption).action((target, options) => {
 		const projectPath = resolve(io.cwd(), options.projectPath);
 		if (target !== void 0 && options.treePath !== void 0) throw new Error("Connect requires exactly one of a name/repository or --tree-path.");
 		if (target !== void 0) {
-			line(io, JSON.stringify(connectProject({
+			emit(io, options.json, connectProject({
 				projectPath,
 				target
-			})));
+			}), formatConnect);
 			return;
 		}
 		if (options.treePath !== void 0) {
-			line(io, JSON.stringify(connectProject({
+			emit(io, options.json, connectProject({
 				projectPath,
 				treePath: resolve(io.cwd(), options.treePath)
-			})));
+			}), formatConnect);
 			return;
 		}
 		throw new Error("Connect requires a managed tree name, GitHub OWNER/REPO, or --tree-path.");
 	});
-	program.command("list").description("List valid clean managed Context Trees.").action(() => {
-		line(io, JSON.stringify(listManagedTrees()));
+	program.command("list").description("List valid clean managed Context Trees.").option(...jsonOption).action((options) => {
+		emit(io, options.json, listManagedTrees(), formatList);
 	});
-	program.command("resolve").description("Resolve the connected Context Tree for a project.").option("--project-path <path>", "project directory", ".").action((options) => {
-		line(io, JSON.stringify(resolveConnection(resolve(io.cwd(), options.projectPath))));
+	program.command("resolve").description("Resolve the connected Context Tree for a project.").option("--project-path <path>", "project directory", ".").option(...jsonOption).action((options) => {
+		emit(io, options.json, resolveConnection(resolve(io.cwd(), options.projectPath)), formatResolve);
 	});
 	program.command("sync").description("Synchronize the connected Context Tree for a project.").option("--project-path <path>", "project directory", ".").action((options) => {
 		line(io, JSON.stringify(syncProject(resolve(io.cwd(), options.projectPath))));
@@ -26514,17 +26607,17 @@ function createContextTreeCli(io = defaultIo) {
 			worktreePath: resolve(io.cwd(), options.worktreePath)
 		})));
 	});
-	program.command("publish").description("Publish the local tree as a new private GitHub repository.").argument("[repository]", "GitHub OWNER/REPO override; defaults to the authenticated account and tree name").option("--project-path <path>", "project directory", ".").action((repository, options) => {
-		line(io, JSON.stringify(publishProject(resolve(io.cwd(), options.projectPath), { repository })));
+	program.command("publish").description("Publish the local tree as a new private GitHub repository.").argument("[repository]", "GitHub OWNER/REPO override; defaults to the authenticated account and tree name").option("--project-path <path>", "project directory", ".").option(...jsonOption).action((repository, options) => {
+		emit(io, options.json, publishProject(resolve(io.cwd(), options.projectPath), { repository }), formatPublish);
 	});
-	program.command("read").description("Read an indexed Context Tree directory or Markdown leaf.").argument("[path]", "tree-relative path", ".").option("--tree-path <path>", "Context Tree root", ".").action((path, options) => {
+	program.command("read").description("Read an indexed Context Tree directory or Markdown leaf.").argument("[path]", "tree-relative path", ".").option("--tree-path <path>", "Context Tree root", ".").option(...jsonOption).action((path, options) => {
 		const treePath = resolve(io.cwd(), options.treePath);
 		if (!verifyTree(treePath).ok) throw new ContextTreeError(CLI_ERROR_CODES.invalidTree, `Refusing to read an invalid Context Tree; run context-tree verify --tree-path ${treePath}.`);
-		line(io, JSON.stringify(readTree(treePath, path)));
+		emit(io, options.json, readTree(treePath, path), formatRead);
 	});
-	program.command("verify").description("Validate Context Tree structure and safety.").option("--tree-path <path>", "Context Tree root", ".").action((options) => {
+	program.command("verify").description("Validate Context Tree structure and safety.").option("--tree-path <path>", "Context Tree root", ".").option(...jsonOption).action((options) => {
 		const result = verifyTree(resolve(io.cwd(), options.treePath));
-		line(io, JSON.stringify(result));
+		emit(io, options.json, result, formatVerify);
 		if (!result.ok) process.exitCode = 1;
 	});
 	program.command("install").description("Install the packaged Context Tree skills into each agent's skill directory.").option("--host <host>", "restrict to one host: claude, codex, or all", "all").option("--project <path>", "install below this project root instead of the home directory").action((options) => {
@@ -26542,19 +26635,27 @@ async function runContextTreeCli(argv = process.argv, io = defaultIo) {
 		return typeof process.exitCode === "number" && process.exitCode !== 0 ? process.exitCode : 0;
 	} catch (error) {
 		if (error instanceof CommanderError && error.exitCode === 0) return 0;
-		const envelope = {
+		const code = error instanceof ContextTreeError ? error.code : CLI_ERROR_CODES.failed;
+		const message = sanitizeCommandOutput(error instanceof Error ? error.message : String(error));
+		if (usesTextErrors(argv)) errline(io, `context-tree: ${message}`);
+		else line(io, JSON.stringify({
 			error: {
-				code: error instanceof ContextTreeError ? error.code : CLI_ERROR_CODES.failed,
-				message: sanitizeCommandOutput(error instanceof Error ? error.message : String(error))
+				code,
+				message
 			},
 			ok: false,
 			schemaVersion: 1
-		};
-		line(io, JSON.stringify(envelope));
+		}));
 		process.exitCode = 1;
 		return 1;
 	}
 }
+/** A text-default command failing without --json reports a human-readable line on stderr. */
+function usesTextErrors(argv) {
+	if (argv.includes("--json")) return false;
+	const subcommand = argv.slice(2).find((token) => !token.startsWith("-"));
+	return subcommand !== void 0 && TEXT_DEFAULT_COMMANDS.has(subcommand);
+}
 //#endregion
 //#region src/cli/index.ts
 await runContextTreeCli();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@first-tree-ai/context-tree",
-  "version": "0.1.8",
+  "version": "0.1.9-alpha.202609020917",
   "description": "Durable, structured project context for coding agents: a CLI plus framework-neutral skills.",
   "type": "module",
   "license": "Apache-2.0",

package/skills/context-tree-connect/SKILL.md

@@ -15,9 +15,9 @@ If `context-tree` is not found, stop and ask the user to run
 Connect exactly one target supplied by the user:
 
 - A managed tree name or GitHub `OWNER/REPO`:
-  `context-tree connect "<name-or-OWNER/REPO>"`.
+  `context-tree connect "<name-or-OWNER/REPO>" --json`.
 - An exact path to an existing Context Tree checkout:
-  `context-tree connect --tree-path "<path>"`.
+  `context-tree connect --tree-path "<path>" --json`.
   That checkout is attached where it already lives and is never copied, moved,
   or deleted.
 

package/skills/context-tree-create/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 If `context-tree` is not found, stop and ask the user to run
 `npm install --global @first-tree-ai/context-tree`.
 
-Run `context-tree create`. Report whether the managed tree was created or
+Run `context-tree create --json`. Report whether the managed tree was created or
 already existed, together with its name, path, and exact commit SHA.
 
 The managed name is derived from the project directory's name. If that name is
@@ -25,7 +25,7 @@ sessions and other agents find it without any host-specific setup. The result's
 `pointer` field reports `written`, `updated`, or `skipped`; when it is not
 `skipped`, tell the user that `AGENTS.md` in their project changed.
 
-After the tree is created or reused, run `context-tree resolve`. When the tree is
+After the tree is created or reused, run `context-tree resolve --json`. When the tree is
 local, ask the user whether to publish it as a private GitHub repository. An
 explicit prior request to publish counts as confirmation; otherwise a "no"
 leaves the tree local, and a "yes" delegates to `$context-tree-publish`. Never

package/skills/context-tree-publish/SKILL.md

@@ -12,7 +12,7 @@ metadata:
 If `context-tree` is not found, stop and ask the user to run
 `npm install --global @first-tree-ai/context-tree`.
 
-Run `context-tree publish`. When the user explicitly supplies an alternative,
+Run `context-tree publish --json`. When the user explicitly supplies an alternative,
 append the validated `OWNER/REPO` argument. Never accept a repository URL.
 
 Publication creates one new private repository, and the local connection update

package/skills/context-tree-read/SKILL.md

@@ -15,7 +15,7 @@ run `npm install --global @first-tree-ai/context-tree`. If it reports
 run `sync` again once.
 
 Use the returned `tree.path` for narrow, task-relevant reads with
-`context-tree read [path] --tree-path "<tree-path>"`. Start at the root index,
+`context-tree read [path] --tree-path "<tree-path>" --json`. Start at the root index,
 then open only the immediate children that bear on the task. Do not scan the
 whole tree.
 

package/skills/context-tree-setup/SKILL.md

@@ -12,14 +12,14 @@ metadata:
 If `context-tree` is not found, stop and ask the user to run
 `npm install --global @first-tree-ai/context-tree`.
 
-Run `context-tree resolve`. If it succeeds, report whether the tree is local or
+Run `context-tree resolve --json`. If it succeeds, report whether the tree is local or
 GitHub-backed, with its canonical path, and stop; the project is already set up.
 
 If `resolve` reports `NO_CONNECTION`, ask the user whether to create a new
 Context Tree or connect an existing one:
 
 - To create, delegate to `$context-tree-create`.
-- To connect, run `context-tree list` and offer every listed managed name, a
+- To connect, run `context-tree list --json` and offer every listed managed name, a
   GitHub `OWNER/REPO`, and an exact disk path. Delegate the chosen target to
   `$context-tree-connect`, which owns the rules for accepting it.