first-tree 0.0.1 → 0.0.3

package/skills/first-tree/engine/rules/framework.ts

@@ -0,0 +1,13 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { SKILL_ROOT } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.hasFramework()) {
+    tasks.push(
+      `\`${SKILL_ROOT}/\` not found — run \`context-tree init\` to install the framework skill bundled with the current \`first-tree\` package`,
+    );
+  }
+  return { group: "Framework", order: 1, tasks };
+}

package/skills/first-tree/engine/rules/index.ts

@@ -0,0 +1,41 @@
+import type { Repo } from "#skill/engine/repo.js";
+import * as agentInstructions from "#skill/engine/rules/agent-instructions.js";
+import * as agentIntegration from "#skill/engine/rules/agent-integration.js";
+import * as ciValidation from "#skill/engine/rules/ci-validation.js";
+import * as framework from "#skill/engine/rules/framework.js";
+import * as members from "#skill/engine/rules/members.js";
+import * as populateTree from "#skill/engine/rules/populate-tree.js";
+import * as rootNode from "#skill/engine/rules/root-node.js";
+
+export interface RuleResult {
+  group: string;
+  order: number;
+  tasks: string[];
+}
+
+interface Rule {
+  evaluate(repo: Repo): RuleResult;
+}
+
+const ALL_RULES: Rule[] = [
+  framework,
+  rootNode,
+  agentInstructions,
+  members,
+  agentIntegration,
+  ciValidation,
+  populateTree,
+];
+
+export function evaluateAll(repo: Repo): RuleResult[] {
+  const results: RuleResult[] = [];
+  for (const rule of ALL_RULES) {
+    const result = rule.evaluate(repo);
+    if (result.tasks.length > 0) {
+      results.push(result);
+    }
+  }
+  return results.sort((a, b) => a.order - b.order);
+}
+
+export { framework, rootNode, agentInstructions, members, agentIntegration, ciValidation, populateTree };

package/skills/first-tree/engine/rules/members.ts

@@ -0,0 +1,21 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.pathExists("members")) {
+    tasks.push("`members/` directory is missing — create it with a NODE.md");
+  } else if (!repo.pathExists("members/NODE.md")) {
+    tasks.push("`members/NODE.md` is missing — create it from the template");
+  }
+  if (repo.hasMembers() && repo.memberCount() === 0) {
+    tasks.push(
+      "Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user",
+    );
+  } else if (!repo.hasMembers()) {
+    tasks.push(
+      "Add at least one member node under `members/`. Analyze the user's code repositories (git history, CODEOWNERS, README contributors) to suggest members, then confirm with the user",
+    );
+  }
+  return { group: "Members", order: 4, tasks };
+}

package/skills/first-tree/engine/rules/populate-tree.ts

@@ -0,0 +1,36 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { INTERACTIVE_TOOL } from "#skill/engine/init.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+
+  tasks.push(
+    `Ask the user whether they want to populate the full context tree now using the **${INTERACTIVE_TOOL}** tool. ` +
+      "Present two options: (1) **Yes — populate the full tree**: the agent will analyze source repositories, " +
+      "create sub-domains, and populate NODE.md files for each domain and sub-domain; " +
+      "(2) **No — I'll do it later**: skip deep population and finish init with just the top-level structure. " +
+      "If the user selects No, check off all remaining items in this section and move on.",
+  );
+
+  tasks.push(
+    "If the user selected Yes: analyze the codebase (and any additional repositories the user provides) to identify " +
+      "logical sub-domains within each top-level domain. For each sub-domain, create a directory with a NODE.md " +
+      "containing proper frontmatter (title, owners) and a description of the sub-domain's purpose, boundaries, " +
+      "and key decisions. Create deeper sub-domains when a domain is large enough to warrant further decomposition.",
+  );
+
+  tasks.push(
+    "Use **sub-tasks** (TaskCreate) to parallelize the population work — create one sub-task per top-level domain " +
+      "so each domain can be populated concurrently. Each sub-task should: read the relevant source code, identify " +
+      "sub-domains, create NODE.md files, and establish soft_links between related domains.",
+  );
+
+  tasks.push(
+    "After all domains are populated, update the root NODE.md to list every top-level domain with a one-line " +
+      "description. Ensure all NODE.md files pass `context-tree verify` — valid frontmatter, no placeholders, " +
+      "and soft_links that resolve correctly.",
+  );
+
+  return { group: "Populate Tree", order: 7, tasks };
+}

package/skills/first-tree/engine/rules/root-node.ts

@@ -0,0 +1,41 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_TEMPLATES_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.pathExists("NODE.md")) {
+    tasks.push(
+      `NODE.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/root-node.md.template\`. ` +
+      "Ask the user for their code repositories or project directories, then analyze the source to determine the project description and domain structure",
+    );
+  } else {
+    const fm = repo.frontmatter("NODE.md");
+    if (fm === null) {
+      tasks.push(
+        "NODE.md exists but has no frontmatter — add frontmatter with title and owners fields",
+      );
+    } else {
+      if (!fm.title || fm.title.startsWith("<")) {
+        tasks.push(
+          "NODE.md has a placeholder title — replace with your organization name",
+        );
+      }
+      if (
+        !fm.owners ||
+        fm.owners.length === 0 ||
+        (fm.owners.length === 1 && fm.owners[0].startsWith("<"))
+      ) {
+        tasks.push(
+          "NODE.md has placeholder owners — set owners to your GitHub username(s)",
+        );
+      }
+    }
+    if (repo.hasPlaceholderNode()) {
+      tasks.push(
+        "NODE.md has placeholder content — ask the user for their code repositories or project directories, then analyze the source to fill in the project description and domain structure",
+      );
+    }
+  }
+  return { group: "Root Node", order: 2, tasks };
+}

package/skills/first-tree/engine/runtime/adapters.ts

@@ -0,0 +1,22 @@
+import { join } from "node:path";
+import {
+  FRAMEWORK_EXAMPLES_DIR,
+  FRAMEWORK_HELPERS_DIR,
+  LEGACY_SKILL_EXAMPLES_DIR,
+  LEGACY_EXAMPLES_DIR,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export const CLAUDE_SETTINGS_PATH = ".claude/settings.json";
+export const CODEX_CONFIG_PATH = ".codex/config.json";
+
+export function claudeCodeExampleCandidates(): string[] {
+  return [
+    join(FRAMEWORK_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_SKILL_EXAMPLES_DIR, "claude-code"),
+    join(LEGACY_EXAMPLES_DIR, "claude-code"),
+  ];
+}
+
+export function injectTreeContextHint(): string {
+  return join(FRAMEWORK_HELPERS_DIR, "inject-tree-context.sh");
+}

package/skills/first-tree/engine/runtime/asset-loader.ts

@@ -0,0 +1,134 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export const SKILL_NAME = "first-tree";
+export const SKILL_ROOT = join("skills", SKILL_NAME);
+export const SKILL_AGENTS_DIR = join(SKILL_ROOT, "agents");
+export const SKILL_REFERENCES_DIR = join(SKILL_ROOT, "references");
+export const FRAMEWORK_ASSET_ROOT = join(SKILL_ROOT, "assets", "framework");
+export const FRAMEWORK_MANIFEST = join(FRAMEWORK_ASSET_ROOT, "manifest.json");
+export const FRAMEWORK_VERSION = join(FRAMEWORK_ASSET_ROOT, "VERSION");
+export const FRAMEWORK_TEMPLATES_DIR = join(FRAMEWORK_ASSET_ROOT, "templates");
+export const FRAMEWORK_WORKFLOWS_DIR = join(FRAMEWORK_ASSET_ROOT, "workflows");
+export const FRAMEWORK_PROMPTS_DIR = join(FRAMEWORK_ASSET_ROOT, "prompts");
+export const FRAMEWORK_EXAMPLES_DIR = join(FRAMEWORK_ASSET_ROOT, "examples");
+export const FRAMEWORK_HELPERS_DIR = join(FRAMEWORK_ASSET_ROOT, "helpers");
+export const INSTALLED_PROGRESS = join(SKILL_ROOT, "progress.md");
+
+export const LEGACY_SKILL_NAME = "first-tree-cli-framework";
+export const LEGACY_SKILL_ROOT = join("skills", LEGACY_SKILL_NAME);
+export const LEGACY_SKILL_ASSET_ROOT = join(
+  LEGACY_SKILL_ROOT,
+  "assets",
+  "framework",
+);
+export const LEGACY_SKILL_VERSION = join(LEGACY_SKILL_ASSET_ROOT, "VERSION");
+export const LEGACY_SKILL_TEMPLATES_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "templates",
+);
+export const LEGACY_SKILL_WORKFLOWS_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "workflows",
+);
+export const LEGACY_SKILL_PROMPTS_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "prompts",
+);
+export const LEGACY_SKILL_EXAMPLES_DIR = join(
+  LEGACY_SKILL_ASSET_ROOT,
+  "examples",
+);
+export const LEGACY_SKILL_PROGRESS = join(LEGACY_SKILL_ROOT, "progress.md");
+
+export const LEGACY_FRAMEWORK_ROOT = ".context-tree";
+export const LEGACY_VERSION = join(LEGACY_FRAMEWORK_ROOT, "VERSION");
+export const LEGACY_PROGRESS = join(LEGACY_FRAMEWORK_ROOT, "progress.md");
+export const LEGACY_TEMPLATES_DIR = join(LEGACY_FRAMEWORK_ROOT, "templates");
+export const LEGACY_WORKFLOWS_DIR = join(LEGACY_FRAMEWORK_ROOT, "workflows");
+export const LEGACY_PROMPTS_DIR = join(LEGACY_FRAMEWORK_ROOT, "prompts");
+export const LEGACY_EXAMPLES_DIR = join(LEGACY_FRAMEWORK_ROOT, "examples");
+
+export type FrameworkLayout = "skill" | "legacy-skill" | "legacy";
+
+function pathExists(root: string, relPath: string): boolean {
+  const fullPath = join(root, relPath);
+  try {
+    return existsSync(fullPath);
+  } catch {
+    return false;
+  }
+}
+
+export function frameworkVersionCandidates(): string[] {
+  return [FRAMEWORK_VERSION, LEGACY_SKILL_VERSION, LEGACY_VERSION];
+}
+
+export function progressFileCandidates(): string[] {
+  return [INSTALLED_PROGRESS, LEGACY_SKILL_PROGRESS, LEGACY_PROGRESS];
+}
+
+export function frameworkTemplateDirCandidates(): string[] {
+  return [
+    FRAMEWORK_TEMPLATES_DIR,
+    LEGACY_SKILL_TEMPLATES_DIR,
+    LEGACY_TEMPLATES_DIR,
+  ];
+}
+
+export function frameworkWorkflowDirCandidates(): string[] {
+  return [
+    FRAMEWORK_WORKFLOWS_DIR,
+    LEGACY_SKILL_WORKFLOWS_DIR,
+    LEGACY_WORKFLOWS_DIR,
+  ];
+}
+
+export function frameworkPromptDirCandidates(): string[] {
+  return [
+    FRAMEWORK_PROMPTS_DIR,
+    LEGACY_SKILL_PROMPTS_DIR,
+    LEGACY_PROMPTS_DIR,
+  ];
+}
+
+export function frameworkExampleDirCandidates(): string[] {
+  return [
+    FRAMEWORK_EXAMPLES_DIR,
+    LEGACY_SKILL_EXAMPLES_DIR,
+    LEGACY_EXAMPLES_DIR,
+  ];
+}
+
+export function resolveFirstExistingPath(
+  root: string,
+  candidates: string[],
+): string | null {
+  for (const candidate of candidates) {
+    if (pathExists(root, candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function detectFrameworkLayout(root: string): FrameworkLayout | null {
+  if (pathExists(root, FRAMEWORK_VERSION)) {
+    return "skill";
+  }
+  if (pathExists(root, LEGACY_SKILL_VERSION)) {
+    return "legacy-skill";
+  }
+  if (pathExists(root, LEGACY_VERSION)) {
+    return "legacy";
+  }
+  return null;
+}
+
+export function isDirectory(root: string, relPath: string): boolean {
+  try {
+    return statSync(join(root, relPath)).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/skills/first-tree/engine/runtime/installer.ts

@@ -0,0 +1,82 @@
+import { copyFileSync, cpSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  FRAMEWORK_ASSET_ROOT,
+  LEGACY_SKILL_ROOT,
+  SKILL_ROOT,
+} from "#skill/engine/runtime/asset-loader.js";
+
+export function resolveBundledPackageRoot(startUrl = import.meta.url): string {
+  let dir = dirname(fileURLToPath(startUrl));
+  while (true) {
+    if (
+      existsSync(join(dir, "package.json")) &&
+      existsSync(join(dir, SKILL_ROOT, "SKILL.md"))
+    ) {
+      return dir;
+    }
+
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+
+  throw new Error(
+    "Could not locate the bundled `first-tree` package root. Reinstall the package and try again.",
+  );
+}
+
+export function resolveCanonicalSkillRoot(sourceRoot: string): string {
+  const directSkillRoot = sourceRoot;
+  if (
+    existsSync(join(directSkillRoot, "SKILL.md")) &&
+    existsSync(join(directSkillRoot, "assets", "framework", "VERSION"))
+  ) {
+    return directSkillRoot;
+  }
+
+  const nestedSkillRoot = join(sourceRoot, SKILL_ROOT);
+  if (
+    existsSync(join(nestedSkillRoot, "SKILL.md")) &&
+    existsSync(join(nestedSkillRoot, "assets", "framework", "VERSION"))
+  ) {
+    return nestedSkillRoot;
+  }
+
+  throw new Error(
+    `Canonical skill not found under ${sourceRoot}. Reinstall the \`first-tree\` package and try again.`,
+  );
+}
+
+export function copyCanonicalSkill(sourceRoot: string, targetRoot: string): void {
+  const src = resolveCanonicalSkillRoot(sourceRoot);
+  const dst = join(targetRoot, SKILL_ROOT);
+  const legacyDst = join(targetRoot, LEGACY_SKILL_ROOT);
+  if (existsSync(dst)) {
+    rmSync(dst, { recursive: true, force: true });
+  }
+  if (legacyDst !== dst && existsSync(legacyDst)) {
+    rmSync(legacyDst, { recursive: true, force: true });
+  }
+  mkdirSync(dirname(dst), { recursive: true });
+  cpSync(src, dst, { recursive: true });
+}
+
+export function renderTemplateFile(
+  frameworkRoot: string,
+  templateName: string,
+  targetRoot: string,
+  targetPath: string,
+): boolean {
+  const src = join(frameworkRoot, "templates", templateName);
+  const dst = join(targetRoot, targetPath);
+  if (existsSync(dst) || !existsSync(src)) {
+    return false;
+  }
+  mkdirSync(dirname(dst), { recursive: true });
+  copyFileSync(src, dst);
+  return true;
+}

package/skills/first-tree/engine/runtime/upgrader.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveCanonicalSkillRoot } from "#skill/engine/runtime/installer.js";
+
+export function compareFrameworkVersions(left: string, right: string): number {
+  const result = left.localeCompare(right, undefined, {
+    numeric: true,
+    sensitivity: "base",
+  });
+  if (result < 0) return -1;
+  if (result > 0) return 1;
+  return 0;
+}
+
+export function readSourceVersion(sourceRoot: string): string | null {
+  const skillRoot = resolveCanonicalSkillRoot(sourceRoot);
+  const versionPath = join(skillRoot, "assets", "framework", "VERSION");
+  try {
+    return readFileSync(versionPath, "utf-8").trim();
+  } catch {
+    return null;
+  }
+}

package/skills/first-tree/engine/upgrade.ts

@@ -0,0 +1,176 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { Repo } from "#skill/engine/repo.js";
+import {
+  FRAMEWORK_WORKFLOWS_DIR,
+  FRAMEWORK_TEMPLATES_DIR,
+  FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+  LEGACY_FRAMEWORK_ROOT,
+  LEGACY_SKILL_ROOT,
+  SKILL_ROOT,
+  type FrameworkLayout,
+} from "#skill/engine/runtime/asset-loader.js";
+import {
+  copyCanonicalSkill,
+  resolveBundledPackageRoot,
+} from "#skill/engine/runtime/installer.js";
+import {
+  compareFrameworkVersions,
+  readSourceVersion,
+} from "#skill/engine/runtime/upgrader.js";
+
+function writeProgress(repo: Repo, content: string): void {
+  const progressPath = join(repo.root, repo.preferredProgressPath());
+  mkdirSync(dirname(progressPath), { recursive: true });
+  writeFileSync(progressPath, content);
+}
+
+function formatUpgradeTaskList(
+  repo: Repo,
+  localVersion: string,
+  packagedVersion: string,
+  layout: FrameworkLayout,
+): string {
+  const lines: string[] = [
+    `# Context Tree Upgrade — v${localVersion} -> v${packagedVersion}\n`,
+    "## Installed Skill",
+    `- [ ] Review local customizations under \`${SKILL_ROOT}/\` and reapply them if needed`,
+    `- [ ] Re-copy any workflow updates you want from \`${FRAMEWORK_WORKFLOWS_DIR}/\` into \`.github/workflows/\``,
+    `- [ ] Re-check any local agent setup that references \`${SKILL_ROOT}/assets/framework/examples/\` or \`${SKILL_ROOT}/assets/framework/helpers/\``,
+    "",
+  ];
+
+  if (layout === "legacy") {
+    lines.push(
+      "## Migration",
+      "- [ ] Remove any stale `.context-tree/` references from repo-specific docs, scripts, or workflow files",
+      "",
+    );
+  }
+
+  if (layout === "legacy-skill") {
+    lines.push(
+      "## Migration",
+      `- [ ] Remove any stale \`${LEGACY_SKILL_ROOT}/\` references from repo-specific docs, scripts, workflow files, or agent config`,
+      "",
+    );
+  }
+
+  if (repo.hasAgentMdMarkers()) {
+    lines.push(
+      "## Agent Instructions",
+      `- [ ] Compare the framework section in \`AGENT.md\` with \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\` and update the content between the markers if needed`,
+      "",
+    );
+  }
+
+  lines.push(
+    "## Verification",
+    `- [ ] \`${FRAMEWORK_VERSION}\` reads \`${packagedVersion}\``,
+    "- [ ] `context-tree verify` passes",
+    "",
+    "---",
+    "",
+    "**Important:** As you complete each task, check it off in" +
+      ` \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`.` +
+      " Run `context-tree verify` when done — it will fail if any" +
+      " items remain unchecked.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+export interface UpgradeOptions {
+  sourceRoot?: string;
+}
+
+export function runUpgrade(repo?: Repo, options?: UpgradeOptions): number {
+  const workingRepo = repo ?? new Repo();
+
+  if (!workingRepo.hasFramework()) {
+    console.error(
+      "Error: no installed framework skill found. Run `context-tree init` first.",
+    );
+    return 1;
+  }
+
+  const layout = workingRepo.frameworkLayout();
+  if (layout === null) {
+    console.error(
+      "Error: no installed framework skill found. Run `context-tree init` first.",
+    );
+    return 1;
+  }
+  const localVersion = workingRepo.readVersion() ?? "unknown";
+  console.log(`Local framework version: ${localVersion}\n`);
+
+  console.log(
+    "Checking the framework skill bundled with this first-tree package...",
+  );
+
+  let sourceRoot: string;
+  try {
+    sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "unknown error";
+    console.error(`Error: ${message}`);
+    return 1;
+  }
+
+  const packagedVersion = readSourceVersion(sourceRoot);
+  if (packagedVersion === null) {
+    console.log(
+      "Could not read the bundled framework version. Reinstall or update `first-tree` and try again.",
+    );
+    return 1;
+  }
+
+  if (
+    localVersion !== "unknown" &&
+    compareFrameworkVersions(localVersion, packagedVersion) > 0
+  ) {
+    console.log(
+      "The installed framework is newer than the skill bundled with this `first-tree` package. Install a newer package version before running `context-tree upgrade`.",
+    );
+    return 1;
+  }
+
+  if (layout === "skill" && packagedVersion === localVersion) {
+    console.log(
+      `Already up to date with the bundled skill (${FRAMEWORK_VERSION} = ${localVersion}).`,
+    );
+    return 0;
+  }
+
+  copyCanonicalSkill(sourceRoot, workingRepo.root);
+  if (layout === "legacy") {
+    rmSync(join(workingRepo.root, LEGACY_FRAMEWORK_ROOT), {
+      recursive: true,
+      force: true,
+    });
+    console.log(
+      "Migrated legacy .context-tree/ layout to skills/first-tree/.",
+    );
+  } else if (layout === "legacy-skill") {
+    console.log(
+      "Migrated skills/first-tree-cli-framework/ to skills/first-tree/.",
+    );
+  } else {
+    console.log(
+      "Refreshed skills/first-tree/ from the bundled first-tree package.",
+    );
+  }
+
+  const output = formatUpgradeTaskList(
+    workingRepo,
+    localVersion,
+    packagedVersion,
+    layout,
+  );
+  console.log(`\n${output}`);
+  writeProgress(workingRepo, output);
+  console.log(`Progress file written to ${workingRepo.preferredProgressPath()}`);
+  return 0;
+}