@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/commands/init-host-os.js

@@ -0,0 +1,44 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { deriveOsArchLabels } from "@kici-dev/engine";
+//#region src/commands/init-host-os.ts
+/**
+* Host-OS helpers for `kici init`.
+*
+* The starter templates target `kici:os:linux`. On a macOS or Windows host that
+* label matches no local dev-plane agent, so the first `kici run push --local`
+* dispatches nothing. These helpers rewrite the scaffolded `runsOn` to the
+* host's own `kici:os:*` label so the first run lands, mirroring how `kici init`
+* already rewrites the default branch.
+*/
+const OS_LABEL_PREFIX = "kici:os:";
+/**
+* The primary `kici:os:*` label the host reports (linux→kici:os:linux,
+* darwin→kici:os:macos, win32→kici:os:windows). Derived from the engine's
+* canonical mapping — the same derivation the local dev-plane routing uses — so
+* the value is never hand-spelled here and always matches what the plane can
+* satisfy.
+*/
+function primaryHostOsLabel(platform, arch) {
+	return deriveOsArchLabels(platform, arch).find((l) => l.startsWith(OS_LABEL_PREFIX)) ?? `${OS_LABEL_PREFIX}${platform}`;
+}
+/**
+* Rewrite a template's `'kici:os:linux'` runsOn to the host's primary OS label.
+* A no-op on a Linux host (the templates already target it).
+*/
+function rewriteRunsOnForHost(content, platform, arch) {
+	const hostLabel = primaryHostOsLabel(platform, arch);
+	if (hostLabel === "kici:os:linux") return content;
+	return content.replaceAll(`'kici:os:linux'`, `'${hostLabel}'`);
+}
+/**
+* Whether to offer the post-init `Run it now?` prompt: interactive (TTY, not CI)
+* and with dependencies installed (not `--mjs`, not `--skip-install`), so the
+* offered `kici run push --local` can compile the workflow it just scaffolded.
+*/
+function shouldOfferFirstRun(env) {
+	return env.isTTY && !env.ci && !env.mjs && !env.skipInstall;
+}
+//#endregion
+export { primaryHostOsLabel, rewriteRunsOnForHost, shouldOfferFirstRun };
+
+//# sourceMappingURL=init-host-os.js.map

package/dist/commands/init.d.ts

@@ -29,6 +29,10 @@ export interface InitOptions {
     privateRegistrySecret?: string;
     /** Skip writing the .kici/AGENTS.md LLM-authoring context file. Default: write it. */
     noAgentsMd?: boolean;
+    /** Force integrate mode: join .kici/ to the detected workspace (skip the prompt). */
+    workspace?: boolean;
+    /** Force standalone mode even inside a workspace (skip the prompt). */
+    standalone?: boolean;
 }
 /**
  * Initialize .kici/ directory with workflow templates

package/dist/commands/init.js

@@ -1,19 +1,22 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { agentsMdTemplate } from "../templates/agents-md.js";
 import { tsconfigTemplate } from "../templates/tsconfig-json.js";
-import { generatePackageJson } from "../templates/package-json.js";
+import { generatePackageJson, sdkDependencyRange } from "../templates/package-json.js";
 import { workflowPaths } from "../templates/index.js";
 import { detectHookTools, findGitDir } from "../hooks/detector.js";
 import { installHook } from "../hooks/installer.js";
 import "../hooks/index.js";
 import { getTypeScriptPaths } from "../execution/sdk-alias.js";
+import { rewriteRunsOnForHost, shouldOfferFirstRun } from "./init-host-os.js";
 import path from "node:path";
 import pc from "picocolors";
 import { access, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { $ } from "zx";
 import { initZx, logger, toErrorMessage } from "@kici-dev/core";
-import { detectPackageManager, installBuildPolicyArgs, installCommand, parsePackageManager } from "@kici-dev/core/package-manager";
+import { detectPackageManager, detectWorkspaceRoot, installBuildPolicyArgs, installCommand, parsePackageManager } from "@kici-dev/core/package-manager";
 import { checkbox, confirm, select } from "@inquirer/prompts";
-import { $ } from "zx";
+import { isCiEnvironment } from "@kici-dev/core/ci-env";
+import os from "node:os";
 //#region src/commands/init.ts
 /**
 * kici init command
@@ -59,6 +62,7 @@ async function initCommand(options = {}) {
 				content = content.replaceAll("targeting('main')", `targeting('${defaultBranch}')`);
 				content = content.replaceAll("targeting the main branch", `targeting the ${defaultBranch} branch`);
 			}
+			content = rewriteRunsOnForHost(content, os.platform(), os.arch());
 			await writeFile(path.join(kiciDir, "workflows", `${workflow}.ts`), content, "utf-8");
 		}
 		logger.info(pc.gray("Creating .kici/tests/"));
@@ -73,34 +77,12 @@ async function initCommand(options = {}) {
 			await writeFile(kiciIgnorePath, kiciIgnoreTemplate, "utf-8");
 		}
 		const devMode = options.useVerdaccioLocal || await detectDevelopmentMode();
-		logger.info(pc.gray("Writing .kici/package.json"));
-		const pkgContent = generatePackageJson(devMode);
-		await writeFile(path.join(kiciDir, "package.json"), pkgContent, "utf-8");
+		const mode = await resolveScaffoldMode(options);
 		const useVerdaccio = devMode;
-		if (useVerdaccio) {
-			logger.info(pc.yellow("Pointing @kici-dev to local Verdaccio registry."));
-			const npmrc = "@kici-dev:registry=http://verdaccio.local:4873\n";
-			await writeFile(path.join(kiciDir, ".npmrc"), npmrc, "utf-8");
-			const rootNpmrc = path.resolve(".npmrc");
-			if (!await checkExists(rootNpmrc)) {
-				logger.info(pc.gray("Writing .npmrc (Verdaccio scope)"));
-				await writeFile(rootNpmrc, npmrc, "utf-8");
-			}
-		}
-		if (!options.mjs) {
-			logger.info(pc.gray("Writing .kici/tsconfig.json"));
-			const tsconfigContent = await generateTsConfig();
-			await writeFile(path.join(kiciDir, "tsconfig.json"), tsconfigContent, "utf-8");
-			await mkdir(path.join(kiciDir, "types"), { recursive: true });
-			logger.info(pc.gray("Created .kici/types/ for generated type declarations"));
-			if (!options.skipInstall) {
-				const pm = await resolvePackageManager(options.packageManager);
-				const [bin, action] = installCommand(pm);
-				const buildPolicyArgs = installBuildPolicyArgs(pm);
-				logger.info(pc.gray(`Running ${bin} ${action}...`));
-				await $`cd ${kiciDir} && ${bin} ${action} ${buildPolicyArgs}`;
-			}
-		}
+		if (mode.kind === "integrate") {
+			logger.info(pc.cyan(`Integrating .kici/ into the ${mode.workspaceKind} workspace at ${mode.workspaceRoot}`));
+			await wireIntegrateDeps(kiciDir, mode.workspaceRoot, devMode, options);
+		} else await wireStandaloneDeps(kiciDir, devMode, options);
 		if (options.privateRegistry) await writePrivateRegistryScaffold(kiciDir, {
 			url: options.privateRegistry,
 			scope: options.privateRegistryScope,
@@ -109,13 +91,17 @@ async function initCommand(options = {}) {
 		if (await shouldWriteAgentsMd(options)) await writeAgentsMd(kiciDir);
 		logger.info(pc.gray("Updating .gitignore"));
 		await updateGitignore(useVerdaccio);
-		if (process.stdout.isTTY && process.env.CI !== "true") {
+		if (process.stdout.isTTY && !isCiEnvironment()) {
 			if (await findGitDir()) await offerHookInstallation(useVerdaccio);
 		}
 		logger.info(pc.green("\n✓ kici initialized successfully!\n"));
 		logger.info(pc.gray("Next steps:"));
 		logger.info(pc.gray("  1. Edit workflows in .kici/workflows/"));
-		if (options.mjs || options.skipInstall) {
+		if (mode.kind === "integrate") {
+			logger.info(pc.gray("  2. Import your workspace packages from .kici/workflows/ (e.g. @your-scope/utils)"));
+			logger.info(pc.gray("  3. Compile: kici compile"));
+			logger.info(pc.gray("  4. Commit .kici/ to your repository\n"));
+		} else if (options.mjs || options.skipInstall) {
 			logger.info(pc.gray("  2. Run your package manager install in .kici/ to generate a lockfile"));
 			logger.info(pc.gray("  3. Preview matching: kici preview push"));
 			logger.info(pc.gray("  4. Commit .kici/ to your repository\n"));
@@ -123,6 +109,23 @@ async function initCommand(options = {}) {
 			logger.info(pc.gray("  2. Preview matching: kici preview push"));
 			logger.info(pc.gray("  3. Commit .kici/ to your repository\n"));
 		}
+		if (shouldOfferFirstRun({
+			isTTY: Boolean(process.stdout.isTTY),
+			ci: isCiEnvironment(),
+			mjs: Boolean(options.mjs),
+			skipInstall: Boolean(options.skipInstall)
+		})) {
+			if (await confirm({
+				message: "Run it now? (kici run push --local)",
+				default: false
+			})) {
+				const { runRoutedCommand } = await import("./run-routed.js");
+				await runRoutedCommand({
+					event: "push",
+					local: true
+				});
+			}
+		}
 		return true;
 	} catch (error) {
 		const message = toErrorMessage(error);
@@ -153,7 +156,7 @@ async function checkExists(targetPath) {
 * @returns Array of workflow names to include
 */
 async function selectWorkflows() {
-	if (!process.stdout.isTTY || process.env.CI === "true") return ["hello-world", "pr-checks"];
+	if (!process.stdout.isTTY || isCiEnvironment()) return ["hello-world", "pr-checks"];
 	const selected = await checkbox({
 		message: "Which workflows would you like to include?",
 		choices: [{
@@ -217,13 +220,133 @@ async function detectDevelopmentMode() {
 *
 * @param override - The raw `--package-manager` flag value, if provided.
 */
-async function resolvePackageManager(override) {
+async function resolvePackageManager(override, dir = process.cwd()) {
 	if (override) {
 		const parsed = parsePackageManager(override);
 		if (!parsed) throw new Error(`Invalid --package-manager value '${override}'. Expected one of: npm, pnpm, yarn.`);
 		return parsed;
 	}
-	return detectPackageManager(process.cwd());
+	return detectPackageManager(dir);
+}
+/** The @kici-dev scope → local Verdaccio registry line written in dev mode. */
+const VERDACCIO_NPMRC = "@kici-dev:registry=http://verdaccio.local:4873\n";
+/** Write .kici/tsconfig.json + the empty types/ dir (TypeScript mode only). */
+async function writeTsConfigAndTypesDir(kiciDir) {
+	logger.info(pc.gray("Writing .kici/tsconfig.json"));
+	await writeFile(path.join(kiciDir, "tsconfig.json"), await generateTsConfig(), "utf-8");
+	await mkdir(path.join(kiciDir, "types"), { recursive: true });
+	logger.info(pc.gray("Created .kici/types/ for generated type declarations"));
+}
+/** Run the given package manager's install in `dir`, with pnpm's build-gate flag. */
+async function runInstall(pm, dir) {
+	const [bin, action] = installCommand(pm);
+	const buildPolicyArgs = installBuildPolicyArgs(pm);
+	logger.info(pc.gray(`Running ${bin} ${action}...`));
+	await $`cd ${dir} && ${bin} ${action} ${buildPolicyArgs}`;
+}
+/**
+* Standalone dep wiring: write .kici/package.json (+ .kici/.npmrc and root
+* .npmrc in dev mode), then tsconfig + isolated install in TypeScript mode.
+*/
+async function wireStandaloneDeps(kiciDir, devMode, options) {
+	logger.info(pc.gray("Writing .kici/package.json"));
+	await writeFile(path.join(kiciDir, "package.json"), generatePackageJson(devMode), "utf-8");
+	if (devMode) {
+		logger.info(pc.yellow("Pointing @kici-dev to local Verdaccio registry."));
+		await writeFile(path.join(kiciDir, ".npmrc"), VERDACCIO_NPMRC, "utf-8");
+		const rootNpmrc = path.resolve(".npmrc");
+		if (!await checkExists(rootNpmrc)) {
+			logger.info(pc.gray("Writing .npmrc (Verdaccio scope)"));
+			await writeFile(rootNpmrc, VERDACCIO_NPMRC, "utf-8");
+		}
+	}
+	if (!options.mjs) {
+		await writeTsConfigAndTypesDir(kiciDir);
+		if (!options.skipInstall) await runInstall(await resolvePackageManager(options.packageManager), kiciDir);
+	}
+}
+/**
+* Integrate dep wiring: NO .kici/package.json (its absence is the
+* externally-managed signal the compiler honors). Add @kici-dev/sdk to the
+* workspace-root manifest, write a root .npmrc in dev mode, write .kici/tsconfig
+* in TypeScript mode, and run a root install.
+*/
+async function wireIntegrateDeps(kiciDir, workspaceRoot, devMode, options) {
+	await addSdkToRootManifest(workspaceRoot, devMode);
+	if (devMode) {
+		const rootNpmrc = path.join(workspaceRoot, ".npmrc");
+		if (!await checkExists(rootNpmrc)) {
+			logger.info(pc.gray("Writing workspace-root .npmrc (Verdaccio scope)"));
+			await writeFile(rootNpmrc, VERDACCIO_NPMRC, "utf-8");
+		}
+	}
+	if (!options.mjs) await writeTsConfigAndTypesDir(kiciDir);
+	if (!options.skipInstall) await runInstall(await resolvePackageManager(options.packageManager, workspaceRoot), workspaceRoot);
+}
+/**
+* Add @kici-dev/sdk to the workspace-root package.json devDependencies.
+* Never clobbers an existing @kici-dev/sdk declaration (dev or prod dep).
+*/
+async function addSdkToRootManifest(workspaceRoot, devMode) {
+	const manifestPath = path.join(workspaceRoot, "package.json");
+	let raw;
+	try {
+		raw = await readFile(manifestPath, "utf-8");
+	} catch {
+		throw new Error(`Cannot integrate: no package.json at workspace root ${workspaceRoot}`);
+	}
+	const pkg = JSON.parse(raw);
+	const existing = pkg.devDependencies?.["@kici-dev/sdk"] ?? pkg.dependencies?.["@kici-dev/sdk"];
+	if (existing) {
+		logger.info(pc.gray(`@kici-dev/sdk already declared in ${manifestPath} (${existing}) — leaving as-is`));
+		return;
+	}
+	const range = sdkDependencyRange(devMode);
+	pkg.devDependencies = {
+		...pkg.devDependencies ?? {},
+		"@kici-dev/sdk": range
+	};
+	await writeFile(manifestPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+	logger.info(pc.gray(`Added @kici-dev/sdk (${range}) to ${manifestPath}`));
+}
+/**
+* Decide standalone vs integrate. Flags win; otherwise, when a workspace is
+* detected, prompt in interactive mode and default to standalone in CI/non-TTY.
+* With no workspace and no --workspace, always standalone (unchanged behavior).
+*/
+async function resolveScaffoldMode(options) {
+	if (options.workspace && options.standalone) throw new Error("Cannot combine --workspace and --standalone.");
+	if (options.standalone) return { kind: "standalone" };
+	const ws = await detectWorkspaceRoot(process.cwd());
+	if (options.workspace) {
+		if (!ws) throw new Error("Cannot integrate: no pnpm/npm/yarn workspace found at or above the current directory. Run from a workspace root, or omit --workspace for a standalone .kici/.");
+		return {
+			kind: "integrate",
+			workspaceRoot: ws.root,
+			workspaceKind: ws.kind
+		};
+	}
+	if (!ws) return { kind: "standalone" };
+	if (!process.stdout.isTTY || isCiEnvironment()) return { kind: "standalone" };
+	return await promptScaffoldMode(ws.kind) === "integrate" ? {
+		kind: "integrate",
+		workspaceRoot: ws.root,
+		workspaceKind: ws.kind
+	} : { kind: "standalone" };
+}
+/** Interactive standalone-vs-integrate select. Defaults to standalone. */
+async function promptScaffoldMode(kind) {
+	return await select({
+		message: `A ${kind} workspace was detected. How should the workflows be set up?`,
+		choices: [{
+			name: "Standalone — self-contained .kici/ with its own package.json",
+			value: "standalone"
+		}, {
+			name: "Integrate — join the workspace; workflows can import your other packages",
+			value: "integrate"
+		}],
+		default: "standalone"
+	});
 }
 /**
 * Generate tsconfig.json content with optional TypeScript path mappings.
@@ -280,7 +403,7 @@ async function writePrivateRegistryScaffold(kiciDir, args) {
 //
 // The agent renders these into the .kici/.npmrc before running \`npm install\`.
 // The token is resolved from the qualified secret reference at dispatch time
-// (the orchestrator looks it up under the named environment's scoped secrets).
+// (the orchestrator looks it up under the named context's scoped secrets).
 import { workflow, job, step } from '@kici-dev/sdk';
 
 export default workflow('private-registry-example', {
@@ -355,7 +478,7 @@ coverage/
 */
 async function shouldWriteAgentsMd(options) {
 	if (options.noAgentsMd) return false;
-	if (!process.stdout.isTTY || process.env.CI === "true") return true;
+	if (!process.stdout.isTTY || isCiEnvironment()) return true;
 	return await confirm({
 		message: "Add LLM authoring context (.kici/AGENTS.md)?",
 		default: true

package/dist/commands/local-trust-root.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Write the local dev plane's `{ issuer, jwks }` trust root to `outFile`.
+ * Returns true on success.
+ */
+export declare function localTrustRootCommand(outFile: string): Promise<boolean>;
+//# sourceMappingURL=local-trust-root.d.ts.map

package/dist/commands/local-trust-root.js

@@ -0,0 +1,52 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { devIdentityPublicJwkFile } from "../local-plane/plane-manager.js";
+import fs from "node:fs";
+import pc from "picocolors";
+import { logger } from "@kici-dev/core";
+//#region src/commands/local-trust-root.ts
+/**
+* `kici local trust-root <file>` — export the offline local dev plane's
+* dev-signed identity trust root as a self-contained `{ issuer, jwks }` file.
+*
+* The plane's dev identity mints tokens with issuer `kici-local` (clearly
+* non-prod). To self-test a dev-signed attestation offline, `kici
+* verify-attestation --trust-root <file>` needs the plane's public JWKS + its
+* issuer, supplied out-of-band. This command writes exactly the shape
+* `verify-attestation`'s `--trust-root` file path consumes.
+*
+* The exported issuer is the fixed sentinel `kici-local` — it can NEVER
+* masquerade as the prod issuer (`https://api.kici.dev`), so verifying the same
+* bundle against the default (prod) trust root still rejects structurally.
+*/
+/** The plane's fixed non-prod dev-identity issuer. */
+const KICI_LOCAL_ISSUER = "kici-local";
+/**
+* Write the local dev plane's `{ issuer, jwks }` trust root to `outFile`.
+* Returns true on success.
+*/
+async function localTrustRootCommand(outFile) {
+	if (!outFile) {
+		logger.error(pc.red("Error: an output file path is required (`kici local trust-root <file>`)."));
+		return false;
+	}
+	const pubFile = devIdentityPublicJwkFile();
+	let pubJwk;
+	try {
+		pubJwk = JSON.parse(fs.readFileSync(pubFile, "utf-8"));
+	} catch {
+		logger.error(pc.red("Error: no dev-signed identity found for the local plane. Boot the plane first (`kici local up`) so it generates + publishes its public key."));
+		return false;
+	}
+	const trustRoot = {
+		issuer: KICI_LOCAL_ISSUER,
+		jwks: { keys: [pubJwk] }
+	};
+	fs.writeFileSync(outFile, JSON.stringify(trustRoot, null, 2) + "\n");
+	logger.info(`${pc.green("✓")} Wrote local dev trust root to ${pc.bold(outFile)} ` + pc.dim(`(issuer ${KICI_LOCAL_ISSUER} — NOT prod)`));
+	logger.info(pc.dim(`Verify a dev-signed bundle offline with:\n  kici verify-attestation --bundle <bundle> --trust-root ${outFile}`));
+	return true;
+}
+//#endregion
+export { localTrustRootCommand };
+
+//# sourceMappingURL=local-trust-root.js.map

package/dist/commands/local.d.ts

@@ -0,0 +1,65 @@
+/**
+ * kici local commands
+ *
+ * Manage the warm, per-user local dev orchestrator plane: a real independent
+ * orchestrator plus a local Postgres (embedded, with a podman fallback) that
+ * `kici run --local` dispatches through. `up` boots or reuses the plane,
+ * `status` reports it plus the control commands, `down` stops it, and `logs`
+ * prints the orchestrator log path.
+ */
+import type { PlaneStatus, PlaneMode } from '../local-plane/plane-manager.js';
+import type { PlaneState } from '../local-plane/plane-liveness.js';
+/**
+ * Boot (or reuse) the local dev plane, honoring the durable attachment record.
+ *
+ * Routes through the same `resolvePlaneForRun` resolver `kici run --local` uses,
+ * so the two commands share one plane-resolution path and never diverge: an
+ * attached + reachable plane comes up hybrid, an attached-but-unreachable plane
+ * falls back to offline with a loud banner, and a never-attached plane comes up
+ * offline. `--offline` forces the independent boot (without clearing the durable
+ * attachment record — only `detach` does that); `--connected` requires an
+ * attached, reachable Platform.
+ */
+export declare function localUpCommand(flags?: {
+    offline?: boolean;
+    connected?: boolean;
+}): Promise<boolean>;
+/**
+ * The machine-readable projection of a plane status.
+ *
+ * An explicit allow-list, NOT `JSON.stringify(status)`. `PlaneStatus` carries
+ * `adminToken` — the bootstrap admin token the CLI presents to the plane's
+ * admin API — so serializing the whole object would publish it on stdout, and
+ * from there into any consumer's logs. `attachment` is omitted for the same
+ * reason in miniature: no consumer needs it, and a field that is never emitted
+ * cannot leak a field added to it later.
+ */
+export interface LocalStatusJson {
+    state: PlaneState;
+    running: boolean;
+    pid: number | null;
+    port: number | null;
+    url: string | null;
+    pgKind: 'embedded' | 'podman' | null;
+    stampVersion: number | null;
+    mode: PlaneMode | null;
+}
+/** Project a PlaneStatus onto the published JSON shape, absent fields as null. */
+export declare function toLocalStatusJson(status: PlaneStatus): LocalStatusJson;
+/** Show the local dev plane status and its control commands. */
+export declare function localStatusCommand(options?: {
+    json?: boolean;
+}): Promise<boolean>;
+/** Stop the local dev plane, reporting success only once the port is released. */
+export declare function localDownCommand(): Promise<boolean>;
+/** Print the local dev plane orchestrator log path. */
+export declare function localLogsCommand(): Promise<boolean>;
+/**
+ * Attach the local dev plane to the hosted Platform so `kici run --local` uses
+ * real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
+ * with the logged-in PAT, then (re)boots the plane hybrid.
+ */
+export declare function localAttachCommand(): Promise<boolean>;
+/** Detach the local dev plane from the Platform and reboot it offline (independent). */
+export declare function localDetachCommand(): Promise<boolean>;
+//# sourceMappingURL=local.d.ts.map

package/dist/commands/local.js

@@ -0,0 +1,206 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { loadGlobalConfig } from "../remote/config.js";
+import { attachPlane, detachPlane, planeDown, planeLogPath, planeStatus } from "../local-plane/plane-manager.js";
+import { resolvePlaneForRun } from "../local-plane/resolve-plane.js";
+import pc from "picocolors";
+import { toErrorMessage } from "@kici-dev/core";
+//#region src/commands/local.ts
+/**
+* kici local commands
+*
+* Manage the warm, per-user local dev orchestrator plane: a real independent
+* orchestrator plus a local Postgres (embedded, with a podman fallback) that
+* `kici run --local` dispatches through. `up` boots or reuses the plane,
+* `status` reports it plus the control commands, `down` stops it, and `logs`
+* prints the orchestrator log path.
+*/
+/** Print the control commands a user needs once the plane is running. */
+function printControlHints() {
+	console.log("");
+	console.log(pc.dim("Control commands:"));
+	console.log(`  ${pc.cyan("kici local status")}   Show plane status`);
+	console.log(`  ${pc.cyan("kici local logs")}     Print the orchestrator log path`);
+	console.log(`  ${pc.cyan("kici local down")}     Stop the plane`);
+}
+/**
+* Boot (or reuse) the local dev plane, honoring the durable attachment record.
+*
+* Routes through the same `resolvePlaneForRun` resolver `kici run --local` uses,
+* so the two commands share one plane-resolution path and never diverge: an
+* attached + reachable plane comes up hybrid, an attached-but-unreachable plane
+* falls back to offline with a loud banner, and a never-attached plane comes up
+* offline. `--offline` forces the independent boot (without clearing the durable
+* attachment record — only `detach` does that); `--connected` requires an
+* attached, reachable Platform.
+*/
+async function localUpCommand(flags = {}) {
+	console.log(pc.dim("Starting the local dev plane…"));
+	const resolved = await resolvePlaneForRun({
+		offline: flags.offline ?? false,
+		connected: flags.connected ?? false
+	});
+	if ("error" in resolved) {
+		console.log(pc.red(`✗ ${resolved.error}`));
+		return false;
+	}
+	const { plane } = resolved;
+	const url = plane.url ?? "";
+	const pg = pc.dim(`(postgres: ${plane.pgKind ?? "unknown"})`);
+	if (resolved.kind === "attached") console.log(pc.green("✓") + ` Local dev plane running (hybrid → Platform, org: ${pc.bold(resolved.orgId)}) at ${pc.bold(url)} ` + pg);
+	else {
+		console.log(pc.green("✓") + ` Local dev plane running (independent/offline) at ${pc.bold(url)} ` + pg);
+		if (resolved.kind === "fallback") console.log(pc.yellow(`  ⚠ Attached, but booted offline: ${resolved.reason}`));
+	}
+	printControlHints();
+	return true;
+}
+/**
+* Render the branch for a plane port held by a process that is not a KiCI plane
+* orchestrator. Kept apart from the not-serving branch because `kici local down`
+* deliberately refuses to signal such a holder, so pointing at it here would
+* send the operator to a command that cannot act.
+*/
+function printForeignHolder(status) {
+	console.log(pc.yellow("⚠") + ` Port ${pc.bold(String(status.port))} is held by a process that is not a KiCI plane orchestrator.`);
+	console.log(pc.dim(`  pid:      ${status.pid ?? "unknown"}`));
+	console.log("The local dev plane cannot start while that process holds the port.");
+	console.log(`Stop it yourself, or point the plane elsewhere with ${pc.cyan("KICI_LOCAL_ORCH_PORT")}.`);
+}
+/**
+* Render the branch for a plane port held by a KiCI plane orchestrator that is
+* not serving this config dir: our own stamped orchestrator failing its
+* readiness probe, or a plane no stamp here accounts for. Split out of
+* `localStatusCommand` so each branch stays readable.
+*
+* The two get different headlines because only one of them has been probed:
+* readiness is checked for a plane we stamped, so `unready` is a measurement,
+* while a plane we did not stamp is only known to be holding the port.
+*/
+function printNotServing(status) {
+	if (status.state === "foreign-kici") {
+		console.log(pc.yellow("⚠") + ` Port ${pc.bold(String(status.port))} is held by a KiCI plane orchestrator this config dir did not start.`);
+		console.log(pc.dim(`  pid:      ${status.pid ?? "unknown"}`));
+		console.log(pc.dim("  owner:    another KiCI plane — no stamp in this config dir"));
+		console.log(`Stop it with ${pc.cyan("kici local down")}.`);
+		return;
+	}
+	console.log(pc.yellow("⚠") + ` Local dev plane is running but NOT ready at ${pc.bold(status.url ?? "")}`);
+	console.log(pc.dim(`  port:     ${status.port}`));
+	console.log(pc.dim(`  pid:      ${status.pid ?? "unknown"}`));
+	if (status.checks && Object.keys(status.checks).length > 0) {
+		const rendered = Object.entries(status.checks).map(([name, ok]) => `${name}=${ok}`).join(" ");
+		console.log(pc.dim(`  checks:   ${rendered}`));
+	}
+	console.log(`Stop it with ${pc.cyan("kici local down")}.`);
+}
+/** Project a PlaneStatus onto the published JSON shape, absent fields as null. */
+function toLocalStatusJson(status) {
+	return {
+		state: status.state,
+		running: status.running,
+		pid: status.pid ?? null,
+		port: status.port ?? null,
+		url: status.url ?? null,
+		pgKind: status.pgKind ?? null,
+		stampVersion: status.stampVersion ?? null,
+		mode: status.mode ?? null
+	};
+}
+/** Show the local dev plane status and its control commands. */
+async function localStatusCommand(options) {
+	const status = await planeStatus();
+	if (options?.json) {
+		console.log(JSON.stringify(toLocalStatusJson(status)));
+		return true;
+	}
+	if (status.state === "stopped") {
+		console.log(pc.yellow("Local dev plane is not running."));
+		console.log(`Start it with ${pc.cyan("kici local up")}.`);
+		return true;
+	}
+	if (status.state === "foreign-unknown") {
+		printForeignHolder(status);
+		return true;
+	}
+	if (status.state !== "ready") {
+		printNotServing(status);
+		return true;
+	}
+	console.log(pc.green("✓") + ` Local dev plane running at ${pc.bold(status.url ?? "")}`);
+	console.log(pc.dim(`  port:     ${status.port}`));
+	console.log(pc.dim(`  pid:      ${status.pid ?? "unknown"}`));
+	console.log(pc.dim(`  postgres: ${status.pgKind ?? "unknown"}`));
+	if (status.mode === "hybrid" && status.attachment) console.log(pc.dim(`  attached: hybrid → Platform (org: ${status.attachment.orgId})`));
+	else console.log(pc.dim("  attached: no (independent/offline)"));
+	printControlHints();
+	return true;
+}
+/** Stop the local dev plane, reporting success only once the port is released. */
+async function localDownCommand() {
+	console.log(pc.dim("Stopping the local dev plane…"));
+	const result = await planeDown();
+	if (!result.stopped) {
+		console.error(pc.red(`✗ Local dev plane NOT stopped: ${result.reason ?? "port still held"}`));
+		if (result.holderPid !== void 0) console.error(pc.dim(`  holder pid: ${result.holderPid}   port: ${result.port}`));
+		return false;
+	}
+	console.log(pc.green("✓") + " Local dev plane stopped.");
+	return true;
+}
+/** Print the local dev plane orchestrator log path. */
+async function localLogsCommand() {
+	console.log(planeLogPath());
+	return true;
+}
+/**
+* Attach the local dev plane to the hosted Platform so `kici run --local` uses
+* real Platform-minted OIDC + attestation. Mints an org-scoped orchestrator key
+* with the logged-in PAT, then (re)boots the plane hybrid.
+*/
+async function localAttachCommand() {
+	const config = await loadGlobalConfig();
+	if (!config.pat) {
+		console.error(pc.red("Not authenticated. Run `kici login` first."));
+		return false;
+	}
+	if (!config.platformEndpoint) {
+		console.error(pc.red("No Platform endpoint configured. Run `kici login` first."));
+		return false;
+	}
+	const orgId = config.activeOrgId;
+	if (!orgId) {
+		console.error(pc.red("No active organization. Select one with `kici org use <org>` before attaching."));
+		return false;
+	}
+	try {
+		console.log(pc.dim("Attaching the local dev plane to the Platform…"));
+		const status = await attachPlane({
+			apiBase: config.platformEndpoint,
+			pat: config.pat,
+			orgId
+		});
+		console.log(pc.green("✓") + ` Local dev plane attached (hybrid) at ${pc.bold(status.url ?? "")} ` + pc.dim(`(org: ${orgId})`));
+		console.log(pc.dim("`kici run --local` now uses real Platform OIDC + attestation. Detach: ") + pc.cyan("kici local detach"));
+		return true;
+	} catch (err) {
+		console.error(pc.red(`Attach failed: ${toErrorMessage(err)}`));
+		return false;
+	}
+}
+/** Detach the local dev plane from the Platform and reboot it offline (independent). */
+async function localDetachCommand() {
+	const config = await loadGlobalConfig();
+	try {
+		console.log(pc.dim("Detaching the local dev plane…"));
+		await detachPlane({ pat: config.pat });
+		console.log(pc.green("✓") + " Local dev plane detached (independent/offline).");
+		return true;
+	} catch (err) {
+		console.error(pc.red(`Detach failed: ${toErrorMessage(err)}`));
+		return false;
+	}
+}
+//#endregion
+export { localAttachCommand, localDetachCommand, localDownCommand, localLogsCommand, localStatusCommand, localUpCommand, toLocalStatusJson };
+
+//# sourceMappingURL=local.js.map