@theholocron/cli 2.1.0 → 2.2.0

package/dist/capabilities/index.d.mts

@@ -1,5 +1,4 @@
 import { ProviderApiError } from "@theholocron/http-client";
-
 //#region src/capabilities/index.d.ts
 /**
  * Capability interfaces — the contracts that providers implement.
@@ -276,7 +275,8 @@ interface Issues extends ProviderIdentity {
   create(input: {
     summary: string;
     body?: string;
-    labels?: string[]; /** Numeric id or exact title (case-insensitive). */
+    labels?: string[];
+    /** Numeric id or exact title (case-insensitive). */
     milestone?: string;
   }): Promise<{
     key: string;
@@ -322,7 +322,8 @@ interface Deployment extends ProviderIdentity {
   /** Create if missing, otherwise return existing. Idempotent. */
   ensureProject(input: {
     name: string;
-    framework?: string; /** "owner/repo" — passed when linking to a Git provider. */
+    framework?: string;
+    /** "owner/repo" — passed when linking to a Git provider. */
     repo?: string;
     rootDirectory?: string;
   }): Promise<DeploymentProject>;

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import path, { basename, dirname, join, relative } from "node:path";
+import path, { basename, dirname, join, relative, resolve } from "node:path";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { createInterface } from "node:readline";
@@ -10,13 +10,13 @@ import { AuthError, ProviderApiError, ProviderApiError as ProviderApiError$1 } f
 import { Entry, findCredentials } from "@napi-rs/keyring";
 import ora from "ora";
 import chalk from "chalk";
+import { homedir } from "node:os";
 import { execFile, execFileSync, spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { createGitHubClient } from "@theholocron/github-client";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
-import { homedir } from "node:os";
 //#region src/capabilities/index.ts
 const CARDINALITY = {
 	source: "single",
@@ -433,6 +433,87 @@ async function tryLoadHint(importer, packageName) {
 	}
 }
 //#endregion
+//#region src/commands/clone.ts
+async function listOrgRepos(org, token, fetchFn) {
+	const repos = [];
+	let url = `https://api.github.com/orgs/${org}/repos?per_page=100&type=all`;
+	while (url) {
+		const res = await fetchFn(url, { headers: {
+			Authorization: `Bearer ${token}`,
+			Accept: "application/vnd.github+json",
+			"X-GitHub-Api-Version": "2022-11-28"
+		} });
+		if (!res.ok) throw new Error(`GitHub API ${res.status}: ${res.statusText} — check that the token has org:read scope`);
+		repos.push(...await res.json());
+		const next = res.headers.get("link")?.match(/<([^>]+)>;\s*rel="next"/);
+		url = next ? next[1] : null;
+	}
+	return repos;
+}
+async function runClone(input) {
+	const print = input.print ?? ((line) => console.log(line));
+	const fetchFn = input.fetch ?? globalThis.fetch;
+	const dryRun = input.dryRun ?? false;
+	const targetDir = resolve(input.dir ?? join(homedir(), "Code", input.org));
+	const exec = input.exec ?? ((cmd, args, opts) => {
+		return { status: spawnSync(cmd, args, {
+			cwd: opts.cwd,
+			stdio: "inherit"
+		}).status };
+	});
+	print(style.header(`Holocron clone — org=${input.org} → ${targetDir}${dryRun ? " (dry-run)" : ""}`));
+	if (!existsSync(targetDir)) if (dryRun) print(style.dim(`  would create ${targetDir}`));
+	else mkdirSync(targetDir, { recursive: true });
+	let repos;
+	try {
+		repos = await listOrgRepos(input.org, input.token, fetchFn);
+	} catch (err) {
+		return {
+			status: "fail",
+			cloned: 0,
+			skipped: 0,
+			failed: 0,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+	let cloned = 0;
+	let skipped = 0;
+	let failed = 0;
+	for (const repo of repos) {
+		const dest = join(targetDir, repo.name.startsWith(".") ? repo.name.slice(1) : repo.name);
+		if (existsSync(dest)) {
+			print(style.dim(`  skip   ${repo.full_name}`));
+			skipped++;
+			continue;
+		}
+		if (dryRun) {
+			print(style.dim(`  would clone ${repo.full_name} → ${dest}`));
+			cloned++;
+			continue;
+		}
+		print(style.step(`  clone  ${repo.full_name}`));
+		if (exec("git", [
+			"clone",
+			repo.ssh_url,
+			dest
+		], { cwd: targetDir }).status !== 0) {
+			print(style.fail(`  failed ${repo.full_name}`));
+			failed++;
+		} else {
+			print(style.success(`  cloned ${repo.name}`));
+			cloned++;
+		}
+	}
+	const summary = `${cloned} cloned, ${skipped} skipped, ${failed} failed`;
+	print(dryRun ? style.dim(`\n  dry-run: ${summary}`) : failed > 0 ? style.fail(`\n  ${summary}`) : style.success(`\n  ${summary}`));
+	return {
+		status: dryRun ? "dry-run" : failed > 0 ? "fail" : "ok",
+		cloned,
+		skipped,
+		failed
+	};
+}
+//#endregion
 //#region src/commands/new.ts
 /**
 * `holocron new <type> <name>` — create a GitHub repo from a template and
@@ -1100,7 +1181,7 @@ var install_default = "name: Install dependencies\ndescription: Install project
 var setup_node_default = "name: Setup Node\ndescription: Install pnpm and Node.js with pnpm dependency caching.\n\ninputs:\n  node-version:\n    description: Node.js version\n    required: false\n    default: \"22.x\"\n\nruns:\n  using: composite\n\n  steps:\n    - name: Setup pnpm\n      if: ${{ hashFiles('pnpm-lock.yaml') != '' }}\n      uses: pnpm/action-setup@b906affcce14559ad1aafd4ab0e942779e9f58b1 # v4\n\n    - name: Setup Node.js\n      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4\n      with:\n        node-version: ${{ hashFiles('.node-version') != '' && '' || inputs.node-version }}\n        node-version-file: ${{ hashFiles('.node-version') != '' && '.node-version' || '' }}\n        cache: ${{ hashFiles('pnpm-lock.yaml') != '' && 'pnpm' || '' }}\n\n    - name: Add node_modules/.bin to PATH\n      shell: bash\n      run: echo \"$GITHUB_WORKSPACE/node_modules/.bin\" >> $GITHUB_PATH\n";
 //#endregion
 //#region src/templates/workflows/audit.yml
-var audit_default$1 = "name: Audit\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      build-script:\n        description: Script to build and upload bundle stats to Codecov\n        type: string\n        required: false\n        default: pnpm build\n    secrets:\n      CODECOV_TOKEN:\n        required: false\n\njobs:\n  bundle-size:\n    name: Audit the bundle size\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    concurrency:\n      group: audit-${{ github.ref }}\n      cancel-in-progress: true\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: eval \"$BUILD_SCRIPT\"\n        name: Build and upload bundle stats\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}\n";
+var audit_default$1 = "name: Audit\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      build-script:\n        description: Script to build and upload bundle stats to Codecov\n        type: string\n        required: false\n        default: pnpm build\n      run-knip:\n        description: Run Knip to detect unused files, exports, and dependencies\n        type: boolean\n        required: false\n        default: false\n      knip-script:\n        description: Script that invokes Knip (must exit non-zero on findings)\n        type: string\n        required: false\n        default: pnpm run audit\n    secrets:\n      CODECOV_TOKEN:\n        required: false\n\njobs:\n  bundle-size:\n    name: Audit the bundle size\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 15\n    concurrency:\n      group: audit-${{ github.ref }}\n      cancel-in-progress: true\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          fetch-depth: 0\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: eval \"$BUILD_SCRIPT\"\n        name: Build and upload bundle stats\n        env:\n          BUILD_SCRIPT: ${{ inputs.build-script }}\n          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}\n\n  knip:\n    name: Knip\n    if: ${{ inputs.run-knip }}\n    permissions:\n      contents: read\n    runs-on: ubuntu-latest\n    timeout-minutes: 10\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        name: Checkout repository\n        with:\n          persist-credentials: false\n\n      - uses: theholocron/.github/.github/actions/setup@main\n        name: Setup\n\n      - run: eval \"$KNIP_SCRIPT\"\n        name: Run Knip\n        env:\n          KNIP_SCRIPT: ${{ inputs.knip-script }}\n";
 //#endregion
 //#region src/templates/workflows/bookkeeping.yml
 var bookkeeping_default$1 = "name: Bookkeeping\n\non: # yamllint disable-line rule:truthy\n  workflow_call:\n    inputs:\n      configuration-path:\n        description: Path to the labeler configuration file in the calling repo\n        type: string\n        required: false\n        default: .github/labeler.yml\n\njobs:\n  label:\n    name: Apply Labels\n    permissions:\n      contents: read\n      pull-requests: write\n    runs-on: ubuntu-latest\n    timeout-minutes: 5\n    concurrency:\n      group: bookkeeping-${{ github.event.pull_request.number || github.event.issue.number }}\n      cancel-in-progress: true\n    steps:\n      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0\n        with:\n          sparse-checkout: ${{ inputs.configuration-path || '.github/labeler.yml' }}\n          sparse-checkout-cone-mode: false\n\n      - uses: github/issue-labeler@c1b0f9f52a63158c4adc09425e858e87b32e9685 # v3.4\n        if: ${{ github.event_name == 'pull_request' && hashFiles(inputs.configuration-path || '.github/labeler.yml') != '' }}\n        # v3.4 bundles Node 20; allow it to run under Actions' current default.\n        env:\n          ACTIONS_ALLOW_USE_UNSECURE_NODE_VERSION: true\n        with:\n          # Fall back to default path when triggered directly (not via workflow_call)\n          # because inputs.* defaults only apply on workflow_call events.\n          configuration-path: ${{ inputs.configuration-path || '.github/labeler.yml' }}\n          include-title: 1\n          include-body: 0\n          sync-labels: 1\n          enable-versioned-regex: 0\n          repo-token: ${{ github.token }}\n";
@@ -3590,7 +3671,8 @@ async function runSetup(input) {
 			"prd"
 		]) {
 			steps.push(await runStep("vault", `ensureEnvironment ${envName}`, dryRun, async () => {
-				return `${envName} ${(await vault.ensureEnvironment(config.name, envName)).alreadyExists ? "exists" : "created"}`;
+				const result = await vault.ensureEnvironment(config.name, envName);
+				return `${envName} ${result.alreadyExists ? "exists" : "created"}`;
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -3686,11 +3768,10 @@ async function fetchExternalSkill(entry) {
 	const res = await fetch(url);
 	if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${url}`);
 	const content = await res.text();
-	if (entry.computedHash) {
-		const actual = createHash("sha256").update(content).digest("hex");
-		if (actual !== entry.computedHash) throw new Error(`hash mismatch for ${entry.source}/${entry.skillPath}: expected ${entry.computedHash}, got ${actual}`);
-	}
-	return content;
+	return {
+		content,
+		stale: !!entry.computedHash && createHash("sha256").update(content).digest("hex") !== entry.computedHash
+	};
 }
 const AGENTS_SKILLS_ROOT = ".agents/skills";
 /** Relative path of the agent-specific symlink. undefined = unsupported agent. */
@@ -3740,6 +3821,7 @@ async function installSkills({ agent, skills, repoRoot }) {
 		installed.push(name);
 	}
 	const externalFailed = [];
+	const externalStale = [];
 	if (missing.length > 0) {
 		let lock = null;
 		try {
@@ -3749,7 +3831,7 @@ async function installSkills({ agent, skills, repoRoot }) {
 			const entry = lock.skills[name];
 			if (!entry) continue;
 			try {
-				const content = await fetchExternalSkill(entry);
+				const { content, stale: isStale } = await fetchExternalSkill(entry);
 				const agentsDir = join(repoRoot, AGENTS_SKILLS_ROOT, name);
 				await mkdir(agentsDir, { recursive: true });
 				await writeFile(join(agentsDir, "SKILL.md"), content);
@@ -3761,6 +3843,7 @@ async function installSkills({ agent, skills, repoRoot }) {
 				await symlink(relative(dirname(symlinkPath), agentsDir).replace(/\\/g, "/"), symlinkPath);
 				missing.splice(missing.indexOf(name), 1);
 				installed.push(name);
+				if (isStale) externalStale.push(name);
 			} catch {
 				missing.splice(missing.indexOf(name), 1);
 				externalFailed.push(name);
@@ -3774,6 +3857,7 @@ async function installSkills({ agent, skills, repoRoot }) {
 	], symlinkFn);
 	const parts = [`installed ${installed.length}`];
 	if (stale.length > 0) parts.push(`pruned: ${stale.join(", ")}`);
+	if (externalStale.length > 0) parts.push(`stale: ${externalStale.join(", ")} (run \`holocron skills update\` to refresh)`);
 	if (externalFailed.length > 0) parts.push(`fetch failed: ${externalFailed.join(", ")}`);
 	if (missing.length > 0) parts.push(`unknown: ${missing.join(", ")}`);
 	return parts.join("; ");
@@ -3799,9 +3883,10 @@ async function copyDirRecursive(src, dest) {
 	}
 }
 async function updateSkillsGitignore(gitignorePath, existingContent, skills, symlinkFn) {
+	const entries = [`/${AGENTS_SKILLS_ROOT}/`, ...skills.map((n) => `/${symlinkFn(n)}`)];
 	const block = [
 		GITIGNORE_BLOCK_START,
-		...[`/${AGENTS_SKILLS_ROOT}/`, ...skills.map((n) => `/${symlinkFn(n)}`)],
+		...entries,
 		GITIGNORE_BLOCK_END
 	].join("\n");
 	let content;
@@ -4509,6 +4594,28 @@ await yargs(hideBin(process.argv)).scriptName("holocron").usage("$0 <command> [o
 	describe: "Directory to search for holocron.config.json"
 }).command("version", "Print the CLI version", () => {}, () => {
 	console.log(`holocron ${CLI_VERSION}`);
+}).command("clone", "Clone all repos in a GitHub org as siblings under a single directory", (y) => y.option("org", {
+	type: "string",
+	demandOption: true,
+	describe: "GitHub org to clone (e.g., theholocron)"
+}).option("dir", {
+	type: "string",
+	describe: "Parent directory to clone into (default: ~/Code/<org>)"
+}), async (argv) => {
+	const tokens = tokenContext(argv.token);
+	if (!tokens) return;
+	const token = tokens.cliTokens?.["github"] ?? tokens.cliToken ?? process.env.GITHUB_TOKEN ?? process.env.HOLOCRON_GITHUB_TOKEN;
+	if (!token) {
+		console.error("clone: GitHub token required — pass --token or set GITHUB_TOKEN");
+		process.exitCode = 1;
+		return;
+	}
+	if ((await runClone({
+		org: argv.org,
+		token,
+		dryRun: argv.dryRun,
+		...argv.dir ? { dir: argv.dir } : {}
+	})).status === "fail") process.exitCode = 1;
 }).command("doctor", "Load the config and run a smoke check against every provider", (y) => y.option("repo", {
 	type: "string",
 	describe: "Repo coords (\"owner/name\"). Defaults to plugin-specific resolution."

package/dist/index.d.mts

@@ -1,6 +1,5 @@
 import { Analytics, Auth, AuthDescription, AuthEvent, AuthEventType, AuthIdentity, AuthUser, CARDINALITY, CapabilityImpls, CapabilityKey, Cardinality, CardinalityFor, Ci, CiRun, CiRunFilter, CiRunStatus, ConnectionStringOptions, CreateAuthUserInput, Deployment, DeploymentProject, DeploymentProjectSettings, DeploymentRecord, DeploymentTarget, DeploymentTrigger, Dns, DnsRecord, DnsRecordType, EnsureResult, Environment, EnvironmentReviewer, Environments, Issue, IssueSearchFilter, Issues, LabelDef, LifecycleResult, LifecycleSlot, NormalizedAuthUser, Notifications, Observability, ParseWebhookInput, ProviderApiError, ProviderIdentity, REQUIRED_CAPABILITIES, RepoRef, RepoSettings, ResolvedCapability, Ruleset, SecretScope, Secrets, Source, StatusCategory, Storage, StorageBranch, TeamEntry, TeamPermission, Tooling, ToolingDoctorReport, TrackerDoctorReport, TrackerUser, Vault, WebhookDashboardInfo, WebhookVerificationError, isMulti } from "./capabilities/index.mjs";
 import { AuthError, RequestOptions, ResolveTokenConfig as ResolveTokenConfig$1, ResolveTokenInput, RestClient, RestClientConfig, createRestClient } from "@theholocron/http-client";
-
 //#region src/auth-resolver.d.ts
 type ResolveTokenConfig = Omit<ResolveTokenConfig$1, "getKeyringToken">;
 /** Wraps `createResolveToken` from `@theholocron/http` and injects the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/cli",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "The Holocron CLI — a pluggable, capability-based orchestrator for spinning up and operating software projects.",
   "homepage": "https://github.com/theholocron/holocron/tree/main/packages/cli#readme",
   "bugs": "https://github.com/theholocron/holocron/issues",