@habitat-ai/cli 0.3.1 → 0.4.1

package/dist/application.d.ts

@@ -9,6 +9,6 @@ export type ExecuteHabitatOptions = Readonly<{
  * Runs one native Oclif invocation over the app-selected Habitat client.
  *
  * Oclif owns command discovery and dispatch; this boundary supplies only the
- * ready workspace client required by the Habitat command plugin.
+ * ready workspace client required by the Habitat commands.
  */
 export declare function executeHabitat({ appRoot, workspaceRoot, args, development, }: ExecuteHabitatOptions): Promise<unknown>;

package/dist/application.js

@@ -1,11 +1,11 @@
-import { bindHabitatClient } from "@habitat-ai/plugin-cli/binding";
+import { createHabitatClientForWorkspace } from "@habitat-ai/sdk";
 import { execute, settings } from "@oclif/core";
-import { createHabitatClientForWorkspace } from "./composition.js";
+import { bindHabitatClient } from "./lib/binding.js";
 /**
  * Runs one native Oclif invocation over the app-selected Habitat client.
  *
  * Oclif owns command discovery and dispatch; this boundary supplies only the
- * ready workspace client required by the Habitat command plugin.
+ * ready workspace client required by the Habitat commands.
  */
 export async function executeHabitat({ appRoot, workspaceRoot, args, development, }) {
     settings.enableAutoTranspile = development === true;

package/dist/commands/check.d.ts

@@ -0,0 +1,15 @@
+import type { HabitatClient } from "@habitat-ai/sdk";
+import { Command } from "@oclif/core";
+type CheckResult = Awaited<ReturnType<HabitatClient["catalog"]["check"]>>;
+/** Projects one selected Habitat catalog check into Oclif. */
+export default class Check extends Command {
+    static description: string;
+    static flags: {
+        readonly instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        readonly owner: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        readonly rule: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        readonly runner: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<CheckResult>;
+}
+export {};

package/dist/commands/check.js

@@ -0,0 +1,32 @@
+import { Command, Flags } from "@oclif/core";
+import { habitatClientFrom } from "../lib/binding.js";
+import { writeJsonResult } from "../lib/output.js";
+/** Projects one selected Habitat catalog check into Oclif. */
+export default class Check extends Command {
+    static description = "Check resolved Habitat applications";
+    static flags = {
+        instance: Flags.string({ description: "Exact Habitat instance identity" }),
+        owner: Flags.string({ description: "Repository project whose applications enter the check" }),
+        rule: Flags.string({
+            description: "Habitat rule identity; repeat to select a rule set",
+            multiple: true,
+        }),
+        runner: Flags.string({ description: "Mechanical runner identity" }),
+    };
+    async run() {
+        const { flags } = await this.parse(Check);
+        const rules = Array.isArray(flags.rule) ? flags.rule : flags.rule ? [flags.rule] : [];
+        const selectors = {
+            ...(flags.instance !== undefined ? { instance: flags.instance } : {}),
+            ...(flags.owner !== undefined ? { owner: flags.owner } : {}),
+            ...(rules.length === 1 ? { rule: rules[0] } : {}),
+            ...(rules.length > 1 ? { rules } : {}),
+            ...(flags.runner !== undefined ? { runner: flags.runner } : {}),
+        };
+        const result = await habitatClientFrom(this.config).catalog.check(Object.keys(selectors).length === 0 ? {} : { selectors });
+        await writeJsonResult(result);
+        if (result._tag !== "Completed" || !result.ok)
+            this.exit(1);
+        return result;
+    }
+}

package/dist/commands/hook.d.ts

@@ -0,0 +1,12 @@
+import type { HabitatClient } from "@habitat-ai/sdk";
+import { Command } from "@oclif/core";
+type HookResult = Awaited<ReturnType<HabitatClient["catalog"]["check"]>>;
+/** Runs one bounded Habitat operation for a repository-owned local hook. */
+export default class Hook extends Command {
+    static description: string;
+    static args: {
+        readonly name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<HookResult>;
+}
+export {};

package/dist/commands/hook.js

@@ -0,0 +1,25 @@
+import { Args, Command } from "@oclif/core";
+import { habitatClientFrom } from "../lib/binding.js";
+import { writeJsonResult } from "../lib/output.js";
+/** Runs one bounded Habitat operation for a repository-owned local hook. */
+export default class Hook extends Command {
+    static description = "Run a Habitat local-hook entrypoint";
+    static args = {
+        name: Args.string({
+            required: true,
+            options: ["agent-stop"],
+            description: "Named Habitat hook operation",
+        }),
+    };
+    async run() {
+        await this.parse(Hook);
+        const result = await habitatClientFrom(this.config).catalog.check({
+            selectors: { runner: "habitat" },
+        });
+        if (result._tag !== "Completed" || !result.ok) {
+            await writeJsonResult(result);
+            this.exit(1);
+        }
+        return result;
+    }
+}

package/dist/commands/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { HabitatClient } from "@habitat-ai/sdk";
+import { Command } from "@oclif/core";
+type ResolveResult = Awaited<ReturnType<HabitatClient["catalog"]["resolve"]>>;
+/** Projects current-workspace Habitat catalog resolution into Oclif. */
+export default class Resolve extends Command {
+    static description: string;
+    run(): Promise<ResolveResult>;
+}
+export {};

package/dist/commands/resolve.js

@@ -0,0 +1,15 @@
+import { Command } from "@oclif/core";
+import { habitatClientFrom } from "../lib/binding.js";
+import { writeJsonResult } from "../lib/output.js";
+/** Projects current-workspace Habitat catalog resolution into Oclif. */
+export default class Resolve extends Command {
+    static description = "Resolve the current Habitat authority catalog";
+    async run() {
+        await this.parse(Resolve);
+        const result = await habitatClientFrom(this.config).catalog.resolve({});
+        await writeJsonResult(result);
+        if (result._tag === "Rejected")
+            this.exit(1);
+        return result;
+    }
+}

package/dist/generators/init.d.ts

@@ -0,0 +1,3 @@
+import { type GeneratorCallback, type Tree } from "@nx/devkit";
+/** Initializes the installed Habitat package inside one Nx consumer. */
+export default function initializeHabitat(tree: Tree): GeneratorCallback | void;

package/dist/generators/init.js

@@ -0,0 +1,10 @@
+import { installPackagesTask } from "@nx/devkit";
+import { initializeHabitatConsumer } from "../nx/initialization.js";
+import { habitatConsumerBinding } from "../nx-generators.js";
+/** Initializes the installed Habitat package inside one Nx consumer. */
+export default function initializeHabitat(tree) {
+    const result = initializeHabitatConsumer(tree, habitatConsumerBinding);
+    if (!result.packageChanged)
+        return;
+    return () => installPackagesTask(tree);
+}

package/dist/generators/remove-hook.d.ts

@@ -0,0 +1,3 @@
+import type { Tree } from "@nx/devkit";
+/** Removes only Habitat's named Codex hook contribution from one Nx consumer. */
+export default function removeHook(tree: Tree): void;

package/dist/generators/remove-hook.js

@@ -0,0 +1,6 @@
+import { removeHabitatHook } from "../nx/initialization.js";
+import { habitatConsumerBinding } from "../nx-generators.js";
+/** Removes only Habitat's named Codex hook contribution from one Nx consumer. */
+export default function removeHook(tree) {
+    removeHabitatHook(tree, habitatConsumerBinding);
+}

package/dist/lib/binding.d.ts

@@ -0,0 +1,10 @@
+import type { HabitatClient } from "@habitat-ai/sdk";
+import { type Config } from "@oclif/core";
+/** Oclif load options carrying the ready Habitat client selected by the app. */
+export type HabitatOclifLoadOptions = Config["options"] & {
+    readonly habitatClient: HabitatClient;
+};
+/** Adds the app-owned Habitat client to one native Oclif configuration. */
+export declare function bindHabitatClient(options: Config["options"], client: HabitatClient): HabitatOclifLoadOptions;
+/** Reads the ready Habitat client from the current native Oclif configuration. */
+export declare function habitatClientFrom(config: Config): HabitatClient;

package/dist/lib/binding.js

@@ -0,0 +1,16 @@
+import { Errors } from "@oclif/core";
+const HABITAT_CLIENT = "habitatClient";
+/** Adds the app-owned Habitat client to one native Oclif configuration. */
+export function bindHabitatClient(options, client) {
+    return Object.freeze({ ...options, [HABITAT_CLIENT]: client });
+}
+/** Reads the ready Habitat client from the current native Oclif configuration. */
+export function habitatClientFrom(config) {
+    if (!hasHabitatClient(config.options)) {
+        throw new Errors.CLIError("The Habitat app did not supply its service binding.");
+    }
+    return config.options.habitatClient;
+}
+function hasHabitatClient(options) {
+    return HABITAT_CLIENT in options && options.habitatClient !== undefined;
+}

package/dist/lib/output.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Writes one complete Habitat command result as JSON before the command returns.
+ *
+ * Awaiting the stream callback prevents Bun from ending the process while a
+ * large stdout write is still buffered at the Oclif process boundary. EPIPE
+ * remains successful because it means the downstream pipe deliberately
+ * stopped reading, matching Oclif's stdout behavior.
+ */
+export declare function writeJsonResult(result: unknown): Promise<void>;

package/dist/lib/output.js

@@ -0,0 +1,22 @@
+/**
+ * Writes one complete Habitat command result as JSON before the command returns.
+ *
+ * Awaiting the stream callback prevents Bun from ending the process while a
+ * large stdout write is still buffered at the Oclif process boundary. EPIPE
+ * remains successful because it means the downstream pipe deliberately
+ * stopped reading, matching Oclif's stdout behavior.
+ */
+export function writeJsonResult(result) {
+    return new Promise((resolve, reject) => {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`, (error) => {
+            if (error && !isBrokenPipe(error)) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function isBrokenPipe(error) {
+    return "code" in error && error.code === "EPIPE";
+}

package/dist/nx/initialization.d.ts

@@ -0,0 +1,45 @@
+import { type PluginConfiguration, type Tree } from "@nx/devkit";
+import { type Static, Type } from "typebox";
+declare const HookGroupSchema: Type.TObject<{
+    _habitat: Type.TOptional<Type.TObject<{
+        identity: Type.TString;
+        revision: Type.TInteger;
+    }>>;
+    hooks: Type.TArray<Type.TUnknown>;
+}>;
+declare const HabitatOwnedHookGroupSchema: Type.TObject<{
+    _habitat: Type.TObject<{
+        identity: Type.TString;
+        revision: Type.TInteger;
+    }>;
+    hooks: Type.TArray<Type.TObject<{
+        type: Type.TLiteral<"command">;
+        command: Type.TString;
+        statusMessage: Type.TString;
+        timeout: Type.TInteger;
+    }>>;
+}>;
+type HookGroup = Static<typeof HookGroupSchema>;
+type HabitatOwnedHookGroup = Static<typeof HabitatOwnedHookGroupSchema>;
+/** App-owned identities and exact predecessor states consumed by native Nx initialization. */
+export type HabitatConsumerBinding = Readonly<{
+    gritPackage: string;
+    hook: HabitatOwnedHookGroup;
+    nxPlugin: string;
+    predecessorHooks: readonly HookGroup[];
+    predecessorNxPlugins: readonly PluginConfiguration[];
+}>;
+/** Observable generator decision needed to schedule the consumer package manager once. */
+export type HabitatInitializationResult = Readonly<{
+    packageChanged: boolean;
+}>;
+/**
+ * Converges one Nx consumer on the app-owned Habitat plugin, hook, and Grit trust.
+ *
+ * Every admission and compatibility decision completes before the first Tree
+ * write, so an incompatible consumer remains byte-for-byte unchanged.
+ */
+export declare function initializeHabitatConsumer(tree: Tree, binding: HabitatConsumerBinding): HabitatInitializationResult;
+/** Removes only Habitat's named hook group while preserving installed Nx integration. */
+export declare function removeHabitatHook(tree: Tree, binding: HabitatConsumerBinding): void;
+export {};

package/dist/nx/initialization.js

@@ -0,0 +1,201 @@
+import { isDeepStrictEqual } from "node:util";
+import { readJson, readNxJson, updateNxJson, writeJson, } from "@nx/devkit";
+import { Type } from "typebox";
+import { Validator } from "typebox/schema";
+const NX_CONFIG_PATH = "nx.json";
+const PACKAGE_PATH = "package.json";
+const CODEX_HOOKS_PATH = ".codex/hooks.json";
+const HabitatHookMarkerSchema = Type.Object({
+    identity: Type.String({
+        minLength: 1,
+        description: "Stable package-owned identity for one Habitat hook contribution.",
+    }),
+    revision: Type.Integer({
+        minimum: 0,
+        description: "Monotonic payload revision for the named Habitat contribution.",
+    }),
+}, { additionalProperties: false, description: "Habitat hook ownership marker." });
+const HookGroupSchema = Type.Object({
+    _habitat: Type.Optional(HabitatHookMarkerSchema),
+    hooks: Type.Array(Type.Unknown(), {
+        description: "Ordered command contributions in one Codex hook group.",
+    }),
+}, { additionalProperties: true, description: "One consumer-owned Codex hook group." });
+const HabitatHookCommandSchema = Type.Object({
+    type: Type.Literal("command", {
+        description: "Codex hook handler kind owned by the Habitat initializer.",
+    }),
+    command: Type.String({
+        minLength: 1,
+        description: "Installed Habitat command executed by the Codex hook.",
+    }),
+    statusMessage: Type.String({
+        minLength: 1,
+        description: "Operator-facing status rendered while Habitat checks run.",
+    }),
+    timeout: Type.Integer({
+        minimum: 1,
+        description: "Maximum seconds allowed for the Habitat hook command.",
+    }),
+}, { additionalProperties: false, description: "One Habitat-owned Codex hook command." });
+const HabitatOwnedHookGroupSchema = Type.Object({
+    _habitat: HabitatHookMarkerSchema,
+    hooks: Type.Array(HabitatHookCommandSchema, {
+        minItems: 1,
+        description: "Commands contributed by the installed Habitat package.",
+    }),
+}, { additionalProperties: false, description: "The named Habitat Codex hook contribution." });
+const CodexHooksSchema = Type.Object({
+    hooks: Type.Optional(Type.Record(Type.String(), Type.Array(HookGroupSchema), {
+        description: "Ordered hook groups keyed by Codex event identity.",
+    })),
+}, { additionalProperties: true, description: "Consumer-owned Codex hook configuration." });
+const ConsumerPackageSchema = Type.Object({
+    trustedDependencies: Type.Optional(Type.Array(Type.String({ minLength: 1 }), {
+        description: "Package lifecycle scripts explicitly trusted by the Bun consumer.",
+    })),
+}, { additionalProperties: true, description: "Nx consumer package metadata." });
+const hooksValidator = new Validator({}, CodexHooksSchema);
+const packageValidator = new Validator({}, ConsumerPackageSchema);
+/**
+ * Converges one Nx consumer on the app-owned Habitat plugin, hook, and Grit trust.
+ *
+ * Every admission and compatibility decision completes before the first Tree
+ * write, so an incompatible consumer remains byte-for-byte unchanged.
+ */
+export function initializeHabitatConsumer(tree, binding) {
+    const nxJson = requireNxJson(tree);
+    const hooks = readHooks(tree);
+    const packageJson = readPackage(tree);
+    const nxPlan = planNxInitialization(nxJson, binding);
+    const hookPlan = planHookInitialization(hooks, binding);
+    const packagePlan = planPackageInitialization(packageJson, binding.gritPackage);
+    if (nxPlan.changed)
+        updateNxJson(tree, nxPlan.value);
+    if (hookPlan.changed)
+        writeJson(tree, CODEX_HOOKS_PATH, hookPlan.value);
+    if (packagePlan.changed)
+        writeJson(tree, PACKAGE_PATH, packagePlan.value);
+    return { packageChanged: packagePlan.changed };
+}
+/** Removes only Habitat's named hook group while preserving installed Nx integration. */
+export function removeHabitatHook(tree, binding) {
+    const hooks = readHooks(tree);
+    const hookPlan = planHookRemoval(hooks, binding);
+    if (hookPlan.changed)
+        writeJson(tree, CODEX_HOOKS_PATH, hookPlan.value);
+}
+function requireNxJson(tree) {
+    const nxJson = readNxJson(tree);
+    if (nxJson === null) {
+        throw new Error("Habitat initialization requires an Nx workspace with nx.json.");
+    }
+    return nxJson;
+}
+function readHooks(tree) {
+    if (!tree.exists(CODEX_HOOKS_PATH))
+        return { hooks: {} };
+    const input = readJson(tree, CODEX_HOOKS_PATH);
+    if (!hooksValidator.Check(input)) {
+        throw new Error(`${CODEX_HOOKS_PATH} is not a supported Codex hook document.`);
+    }
+    return input;
+}
+function readPackage(tree) {
+    if (!tree.exists(PACKAGE_PATH)) {
+        throw new Error("Habitat initialization requires an Nx workspace package.json.");
+    }
+    const input = readJson(tree, PACKAGE_PATH);
+    if (!packageValidator.Check(input)) {
+        throw new Error("package.json is not a supported Nx consumer package document.");
+    }
+    return input;
+}
+function planNxInitialization(nxJson, binding) {
+    const plugins = nxJson.plugins ?? [];
+    const matches = plugins.filter((plugin) => hasPluginIdentity(plugin, binding.nxPlugin) ||
+        binding.predecessorNxPlugins.some((predecessor) => hasPluginIdentity(plugin, typeof predecessor === "string" ? predecessor : predecessor.plugin)));
+    if (matches.length > 1) {
+        throw new Error("nx.json contains multiple Habitat Nx plugin registrations.");
+    }
+    const match = matches[0];
+    if (match === binding.nxPlugin)
+        return { changed: false, value: nxJson };
+    if (match !== undefined &&
+        !binding.predecessorNxPlugins.some((predecessor) => isDeepStrictEqual(predecessor, match))) {
+        throw new Error("nx.json contains an incompatible Habitat Nx plugin registration.");
+    }
+    const nextPlugins = match === undefined
+        ? [...plugins, binding.nxPlugin]
+        : plugins.map((plugin) => (plugin === match ? binding.nxPlugin : plugin));
+    return { changed: true, value: { ...nxJson, plugins: nextPlugins } };
+}
+function planHookInitialization(hooks, binding) {
+    const location = oneOwnedHookLocation(hooks, binding);
+    if (location !== undefined && isDeepStrictEqual(location.group, binding.hook)) {
+        return { changed: false, value: hooks };
+    }
+    if (location !== undefined &&
+        !binding.predecessorHooks.some((predecessor) => isDeepStrictEqual(predecessor, location.group))) {
+        throw new Error(`${CODEX_HOOKS_PATH} contains an incompatible Habitat hook contribution.`);
+    }
+    const events = hooks.hooks ?? {};
+    const stop = events.Stop ?? [];
+    const nextStop = location === undefined
+        ? [...stop, binding.hook]
+        : stop.map((group, index) => (index === location.index ? binding.hook : group));
+    return {
+        changed: true,
+        value: { ...hooks, hooks: { ...events, Stop: nextStop } },
+    };
+}
+function planHookRemoval(hooks, binding) {
+    const location = oneOwnedHookLocation(hooks, binding);
+    if (location === undefined)
+        return { changed: false, value: hooks };
+    if (!isDeepStrictEqual(location.group, binding.hook) &&
+        !binding.predecessorHooks.some((predecessor) => isDeepStrictEqual(predecessor, location.group))) {
+        throw new Error(`${CODEX_HOOKS_PATH} contains an incompatible Habitat hook contribution.`);
+    }
+    const events = hooks.hooks ?? {};
+    const stop = events.Stop ?? [];
+    return {
+        changed: true,
+        value: {
+            ...hooks,
+            hooks: { ...events, Stop: stop.filter((_group, index) => index !== location.index) },
+        },
+    };
+}
+function planPackageInitialization(packageJson, gritPackage) {
+    const trusted = packageJson.trustedDependencies ?? [];
+    const matches = trusted.filter((dependency) => dependency === gritPackage);
+    if (matches.length > 1) {
+        throw new Error(`package.json contains duplicate ${gritPackage} trust entries.`);
+    }
+    if (matches.length === 1)
+        return { changed: false, value: packageJson };
+    return {
+        changed: true,
+        value: { ...packageJson, trustedDependencies: [...trusted, gritPackage] },
+    };
+}
+function oneOwnedHookLocation(hooks, binding) {
+    const identity = binding.hook._habitat.identity;
+    const locations = Object.entries(hooks.hooks ?? {}).flatMap(([event, groups]) => groups.flatMap((group, index) => {
+        const marked = group._habitat?.identity === identity;
+        const predecessor = binding.predecessorHooks.some((candidate) => isDeepStrictEqual(candidate, group));
+        return marked || predecessor ? [{ event, group, index }] : [];
+    }));
+    if (locations.length > 1) {
+        throw new Error(`${CODEX_HOOKS_PATH} contains multiple Habitat hook contributions.`);
+    }
+    const location = locations[0];
+    if (location !== undefined && location.event !== "Stop") {
+        throw new Error(`${CODEX_HOOKS_PATH} contains a Habitat hook contribution outside Stop.`);
+    }
+    return location;
+}
+function hasPluginIdentity(plugin, identity) {
+    return plugin === identity || (typeof plugin === "object" && plugin.plugin === identity);
+}

package/dist/nx/projection.d.ts

@@ -0,0 +1,29 @@
+import type { HabitatClient } from "@habitat-ai/sdk";
+import type { CreateNodes, TargetConfiguration } from "@nx/devkit";
+type ResolveCatalogClient = {
+    readonly catalog: Pick<HabitatClient["catalog"], "resolve">;
+};
+type TargetInput = NonNullable<TargetConfiguration["inputs"]>[number];
+/**
+ * Supplies the ready Habitat client for the workspace being projected by Nx.
+ *
+ * The Habitat app owns this capability because Nx plugin options are serialized
+ * configuration and cannot carry a client, provider, or runtime handle.
+ */
+export type HabitatClientForWorkspace = (workspaceRoot: string) => ResolveCatalogClient | Promise<ResolveCatalogClient>;
+/** App-owned runtime and provider facts required for sound target caching. */
+export type HabitatNxBinding = {
+    readonly clientForWorkspace: HabitatClientForWorkspace;
+    readonly runtimeInputs: readonly [TargetInput, ...TargetInput[]];
+};
+/**
+ * Projects resolved Habitat applications and compatibility rules into native Nx targets.
+ *
+ * The factory receives the app-owned workspace client and runtime cache facts.
+ * It does not select providers, discover authority, execute checks, or name
+ * projects.
+ */
+export declare function createHabitatNxPlugin(binding: HabitatNxBinding): Readonly<{
+    createNodes: CreateNodes<undefined>;
+}>;
+export {};