@fjall/ai-tools 3.5.2 → 3.6.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export type { ToolTier, ToolSpec, AiToolName } from "./types.js";
 export { AI_TOOL_NAMES } from "./types.js";
 export { AI_TOOL_REGISTRY, getToolSpec } from "./registry.js";
+export { MANAGE_DOMAIN_MUTATION_COMMANDS, MANAGE_DOMAIN_MUTATION_CONTRACT, MANAGE_DOMAIN_MUTATION_SUMMARY, buildMutationCommands, } from "./manageDomainCommands.js";
+export type { ManageDomainMutationCommand } from "./manageDomainCommands.js";
 export * from "./schemas/index.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { AI_TOOL_NAMES } from "./types.js";
 export { AI_TOOL_REGISTRY, getToolSpec } from "./registry.js";
+export { MANAGE_DOMAIN_MUTATION_COMMANDS, MANAGE_DOMAIN_MUTATION_CONTRACT, MANAGE_DOMAIN_MUTATION_SUMMARY, buildMutationCommands, } from "./manageDomainCommands.js";
 export * from "./schemas/index.js";

package/dist/manageDomainCommands.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Single source of truth for the manage_domain mutation-command catalogue.
+ *
+ * The registry description, the webapp executor's mutation_commands result,
+ * and the webapp system prompt all enumerate these commands; each copy must
+ * be DERIVED from this catalogue so the enumerations cannot drift. Content
+ * ported verbatim from the webapp executor's buildMutationCommands
+ * (webapp app/.server/services/ai/tools/manageDomain.ts), which imports it
+ * back from here once the swap phase lands.
+ */
+/** One ceremony-gated (or safe) CLI command the read-only tool relays. */
+export interface ManageDomainMutationCommand {
+    /** CLI invocation template; "<zone>" marks the zone argument. */
+    command: string;
+    purpose: string;
+    /** How the destruction ceremony gates this command; null for safe verbs. */
+    ceremony: string | null;
+}
+/**
+ * The no-destructive-consent contract, phrased the way the CLI's exit-4
+ * (DESTRUCTION_WITHHELD) help text and the agent destruction-gate recipe
+ * phrase it, so the model relays the ceremony instead of trying to bypass it.
+ */
+export declare const MANAGE_DOMAIN_MUTATION_CONTRACT: readonly string[];
+/** Every mutation command the manage_domain tool relays but never executes. */
+export declare const MANAGE_DOMAIN_MUTATION_COMMANDS: readonly ManageDomainMutationCommand[];
+/**
+ * The catalogue's command verbs joined with "/" -- interpolated into the
+ * registry description (and, post-swap, the webapp system prompt) so every
+ * prose enumeration is derived from the one list and cannot drift.
+ */
+export declare const MANAGE_DOMAIN_MUTATION_SUMMARY: string;
+/**
+ * The mutation_commands executor payload: the contract plus the catalogue
+ * with "<zone>" substituted when the caller already knows the zone. The
+ * caller passes an already-normalised zone (the webapp keeps
+ * normaliseRecordName at its boundary); ceremony prose placeholders such as
+ * "<name>/<TYPE>" are consent syntax, never substituted.
+ */
+export declare function buildMutationCommands(zone?: string): {
+    contract: string[];
+    commands: ManageDomainMutationCommand[];
+};

package/dist/manageDomainCommands.js

@@ -0,0 +1,98 @@
+/**
+ * Single source of truth for the manage_domain mutation-command catalogue.
+ *
+ * The registry description, the webapp executor's mutation_commands result,
+ * and the webapp system prompt all enumerate these commands; each copy must
+ * be DERIVED from this catalogue so the enumerations cannot drift. Content
+ * ported verbatim from the webapp executor's buildMutationCommands
+ * (webapp app/.server/services/ai/tools/manageDomain.ts), which imports it
+ * back from here once the swap phase lands.
+ */
+/** Placeholder substituted by {@link buildMutationCommands} when a zone is known. */
+const ZONE_PLACEHOLDER = "<zone>";
+/**
+ * The no-destructive-consent contract, phrased the way the CLI's exit-4
+ * (DESTRUCTION_WITHHELD) help text and the agent destruction-gate recipe
+ * phrase it, so the model relays the ceremony instead of trying to bypass it.
+ */
+export const MANAGE_DOMAIN_MUTATION_CONTRACT = [
+    "This tool is read-only: it never executes domain mutations and never holds destructive-consent power. Run the commands below from the repository's CLI instead.",
+    "Destructive domain surfaces stop at an unconditional destruction gate — no flag disengages it, and --auto-approve, --skip-confirmation, --force and approval tokens never satisfy it. The command stops with exit 4 (DESTRUCTION_WITHHELD): success-shaped — nothing was deleted, nothing was deployed — and prints a ticket naming each affected record.",
+    "Relay the ticket to the user verbatim and let them pick each row's verb — never self-select a destructive verb on the user's behalf: 'recreate' destroys the live record's data and 'forget' abandons it.",
+    "Consent is per-row and exact: --remediate '<name>/<TYPE>[@<setIdentifier>]'=recreate (repeatable; exact spelling from the ticket — the @ tail appears on routing-policy variants), optionally bound with --destruction-consent-digest <digest>. A misspelt name, surplus consent, or illegal verb fails closed with a per-name verdict table.",
+];
+/** Every mutation command the manage_domain tool relays but never executes. */
+export const MANAGE_DOMAIN_MUTATION_COMMANDS = [
+    {
+        command: `fjall create domain --name ${ZONE_PLACEHOLDER}`,
+        purpose: "Register a domain (add --external when DNS stays managed outside Fjall).",
+        ceremony: null,
+    },
+    {
+        command: `fjall domain import ${ZONE_PLACEHOLDER} --from-route53`,
+        purpose: "Migrate existing DNS in — curates infrastructure.ts; the first deploy of an adopted zone runs the takeover ceremony.",
+        ceremony: null,
+    },
+    {
+        command: `fjall domain deploy ${ZONE_PLACEHOLDER}`,
+        purpose: "Apply domain infrastructure ('fjall deploy domain' is the same operation, same flags, same exit codes).",
+        ceremony: "Deploying an adopted live zone stops at a record-takeover ticket: one consent per row, --remediate '<name>/<TYPE>[@<setIdentifier>]'=recreate; exit 4 means consent was withheld and nothing was deployed.",
+    },
+    {
+        command: `fjall domain sync ${ZONE_PLACEHOLDER} --fix`,
+        purpose: "Delete residue records (the records sync_report classifies 'residue').",
+        ceremony: "Same consent shape: --remediate '<name>/<TYPE>[@<setIdentifier>]'=recreate. 'unknown' rows never appear on the ticket — classification fails closed; exit 4 means nothing was deleted.",
+    },
+    {
+        command: `fjall domain delegate ${ZONE_PLACEHOLDER}`,
+        purpose: "Write (or report) a delegated child's NS records into the parent zone.",
+        ceremony: null,
+    },
+    {
+        command: `fjall domain destroy ${ZONE_PLACEHOLDER}`,
+        purpose: "Destroy the domain stack and its hosted zone.",
+        ceremony: "Apex row: --remediate '<zoneName>'=recreate; delegated-child NS row: --remediate '<childZone>/NS'=recreate (or =forget when the parent cannot delete the record). Children are NS-delete-first; exit 4 means nothing was destroyed.",
+    },
+];
+/**
+ * Distinguishing verb of a catalogue command: the first token after the
+ * binary name that is neither the "domain" noun nor a flag, plus any mode
+ * flags positioned after the zone argument (so "sync" reads "sync --fix" --
+ * bare "sync" is the read-only report, not a mutation).
+ */
+function mutationCommandVerb(command) {
+    const tokens = command.split(" ");
+    const verb = tokens
+        .slice(1)
+        .find((token) => token !== "domain" &&
+        token !== ZONE_PLACEHOLDER &&
+        !token.startsWith("--"));
+    const zoneIndex = tokens.indexOf(ZONE_PLACEHOLDER);
+    const modeFlags = zoneIndex === -1
+        ? []
+        : tokens.slice(zoneIndex + 1).filter((token) => token.startsWith("--"));
+    return [verb ?? command, ...modeFlags].join(" ");
+}
+/**
+ * The catalogue's command verbs joined with "/" -- interpolated into the
+ * registry description (and, post-swap, the webapp system prompt) so every
+ * prose enumeration is derived from the one list and cannot drift.
+ */
+export const MANAGE_DOMAIN_MUTATION_SUMMARY = MANAGE_DOMAIN_MUTATION_COMMANDS.map((entry) => mutationCommandVerb(entry.command)).join("/");
+/**
+ * The mutation_commands executor payload: the contract plus the catalogue
+ * with "<zone>" substituted when the caller already knows the zone. The
+ * caller passes an already-normalised zone (the webapp keeps
+ * normaliseRecordName at its boundary); ceremony prose placeholders such as
+ * "<name>/<TYPE>" are consent syntax, never substituted.
+ */
+export function buildMutationCommands(zone) {
+    const target = zone ?? ZONE_PLACEHOLDER;
+    return {
+        contract: [...MANAGE_DOMAIN_MUTATION_CONTRACT],
+        commands: MANAGE_DOMAIN_MUTATION_COMMANDS.map((entry) => ({
+            ...entry,
+            command: entry.command.replaceAll(ZONE_PLACEHOLDER, target),
+        })),
+    };
+}

package/dist/registry.d.ts

@@ -3,7 +3,8 @@
  *
  * This is the single source of truth for tool names, descriptions, tiers,
  * and input schemas. The webapp imports these to build the Anthropic API
- * tool array; the CLI imports them for AXI input validation.
+ * tool array; it is currently the package's only consumer (the CLI has no
+ * dependency on @fjall/ai-tools).
  */
 import type { ToolSpec } from "./types.js";
 /** All AI tool specifications, ordered: read tools first, then write tools. */

package/dist/registry.js

@@ -3,7 +3,8 @@
  *
  * This is the single source of truth for tool names, descriptions, tiers,
  * and input schemas. The webapp imports these to build the Anthropic API
- * tool array; the CLI imports them for AXI input validation.
+ * tool array; it is currently the package's only consumer (the CLI has no
+ * dependency on @fjall/ai-tools).
  */
 import { queryInfrastructureSchema } from "./schemas/queryInfrastructure.js";
 import { queryComplianceSchema } from "./schemas/queryCompliance.js";
@@ -19,6 +20,7 @@ import { manageSecretSchema } from "./schemas/manageSecret.js";
 import { updateConfigurationSchema } from "./schemas/updateConfiguration.js";
 import { manageDomainSchema } from "./schemas/manageDomain.js";
 import { provisionRegionSchema } from "./schemas/provisionRegion.js";
+import { MANAGE_DOMAIN_MUTATION_SUMMARY } from "./manageDomainCommands.js";
 function spec(name, description, inputSchema, tier, requiredRole) {
     return { name, description, inputSchema, tier, requiredRole };
 }
@@ -38,7 +40,7 @@ export const AI_TOOL_REGISTRY = [
     spec("trigger_deployment", "Trigger a new deployment for an application. Verifies the application exists, has a connected AWS account and repository, and no active deployment is running. Creates a deployment record and enqueues it for processing.", triggerDeploymentSchema, "write", "admin"),
     spec("manage_secret", "Manage application secrets stored in AWS SSM Parameter Store. Supports: list (show secret names without values), set (create or update), and delete. Never exposes secret values — the get operation is intentionally excluded.", manageSecretSchema, "write", "admin"),
     spec("update_configuration", "Update an application's configuration — name, description, or config path. Only safe, non-security-sensitive fields can be changed. At least one field must be provided.", updateConfigurationSchema, "write", "admin"),
-    spec("manage_domain", "Read-only domain management mirroring the CLI domain surface. Operations: list (declared domains with live zone and stack status), records_list (every live record with its ownership classification — declared/satellite/residue/unknown; unknown is never remediable, classification fails closed), sync_report (the same classification as a read-only report — this tool never deletes records), verify (DNS nameserver delegation check), and mutation_commands (the exact ceremony-gated CLI commands for deploy/sync --fix/destroy/delegate, which this tool never executes — destructive consent stays with the user).", manageDomainSchema, "read"),
+    spec("manage_domain", `Read-only domain management mirroring the CLI domain surface. Operations: list (declared domains with live zone and stack status), records_list (every live record with its ownership classification - declared/satellite/residue/unknown; unknown is never remediable, classification fails closed), sync_report (the same classification as a read-only report - this tool never deletes records), verify (DNS nameserver delegation check), and mutation_commands (the exact ceremony-gated CLI commands for ${MANAGE_DOMAIN_MUTATION_SUMMARY}, which this tool never executes - destructive consent stays with the user).`, manageDomainSchema, "read"),
     spec("provision_region", "Add an AWS region to the organisation and deploy infrastructure to it. Shows a consequence preview (affected accounts, deployment shape) before asking the user to confirm. Requires admin role.", provisionRegionSchema, "write", "admin"),
 ];
 /** Look up a tool spec by name. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/ai-tools",
-  "version": "3.5.2",
+  "version": "3.6.0",
   "description": "Shared AI tool schemas and registry for Fjall webapp and CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "gitHead": "f59755647b2fd81ff692a3545e8e199d93c3bdf8"
+  "gitHead": "10366db602d7e80669e22825a52071a47e05c3b7"
 }