handoff-app 2.0.0-4 → 2.0.0-6

package/dist/app-builder/build.js

@@ -40,13 +40,14 @@ const p = __importStar(require("@clack/prompts"));
 const cross_spawn_1 = __importDefault(require("cross-spawn"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const config_1 = require("../config");
 const components_1 = require("../pipeline/components");
 const patterns_1 = require("../pipeline/patterns");
+const resolve_1 = require("../registry/asset-storage/resolve");
+const driver_1 = require("../registry/db/driver");
 const builder_1 = __importDefault(require("../transformers/preview/component/builder"));
 const css_1 = require("../transformers/preview/component/css");
 const javascript_1 = require("../transformers/preview/component/javascript");
-const driver_1 = require("../registry/db/driver");
-const resolve_1 = require("../registry/asset-storage/resolve");
 const logger_1 = require("../utils/logger");
 const client_config_1 = require("./client-config");
 const nav_shell_1 = require("./nav-shell");
@@ -216,6 +217,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
     // Resolved runtime mode + registry connection inputs (names only) baked into the Next bundle so the
     // deployed registry app resolves its mode/DB env-var name without any build-machine filesystem.
     const escapedRuntimeMode = escapeForSingleQuotedJsString(runtimeMode);
+    const escapedMcpEnabled = escapeForSingleQuotedJsString(String((0, config_1.isMcpEnabled)(handoff.config)));
     const escapedRegistryDriver = escapeForSingleQuotedJsString((0, driver_1.resolveRegistryDriver)(handoff.config));
     const escapedDatabaseUrlEnv = escapeForSingleQuotedJsString((0, driver_1.resolveDatabaseUrlEnv)(handoff.config));
     // Asset storage selection baked (provider + module + env-var names + non-secret options JSON).
@@ -233,6 +235,7 @@ const initializeProjectApp = (handoff_1, ...args_1) => __awaiter(void 0, [handof
         '%HANDOFF_EXPORT_PATH%': escapedExportPath,
         '%HANDOFF_WEBSOCKET_PORT%': escapedWebsocketPort,
         '%HANDOFF_RUNTIME_MODE%': escapedRuntimeMode,
+        '%HANDOFF_MCP_ENABLED%': escapedMcpEnabled,
         '%HANDOFF_REGISTRY_DRIVER%': escapedRegistryDriver,
         '%HANDOFF_REGISTRY_DATABASE_URL_ENV%': escapedDatabaseUrlEnv,
         '%HANDOFF_ASSET_STORAGE_ADAPTER%': escapedAssetStorageAdapter,
@@ -426,12 +429,16 @@ containers, custom Node servers, and other non-Vercel hosts.
 /**
  * Resolve the set of npm packages the packaged registry app must be able to `require`/`import` at
  * runtime, given the configured database driver. `next`/`react`/`react-dom` run the server and React
- * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the driver
- * package is driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
+ * runtime; `drizzle-orm` backs both the request-time DB client and the migration runner; the MCP SDK
+ * (and its `zod` peer) is only needed when `/api/mcp/` is enabled; the driver package is
+ * driver-specific (the Neon serverless driver also needs `ws` for its Node WebSocket transport).
  */
 const getRequiredRegistryRuntimeModules = (handoff) => {
     var _a;
     const base = ['next', 'next-auth', 'react', 'react-dom', 'drizzle-orm'];
+    if ((0, config_1.isMcpEnabled)(handoff.config)) {
+        base.push('@modelcontextprotocol/sdk', 'zod');
+    }
     const driver = (0, driver_1.resolveRegistryDriver)(handoff.config);
     const driverModules = driver === 'neon' ? ['@neondatabase/serverless', 'ws'] : ['pg'];
     // Asset-storage SDKs the deployed registry must be able to load at request time. The pre-packaged

package/dist/app-builder/client-config.js

@@ -65,6 +65,7 @@ const buildServerRuntimeConfig = (config, modeOverride) => {
     const assetStorage = (0, resolve_1.resolveAssetStorageFromConfig)(config);
     return {
         mode: (_b = modeOverride !== null && modeOverride !== void 0 ? modeOverride : (_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mode) !== null && _b !== void 0 ? _b : 'workspace',
+        mcp: (0, config_1.isMcpEnabled)(config),
         registry: {
             driver: (0, driver_1.resolveRegistryDriver)(config),
             databaseUrlEnv: (0, driver_1.resolveDatabaseUrlEnv)(config),

package/dist/app-builder/nav-shell.js

@@ -14,10 +14,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateNavShell = exports.generateDefaultPages = exports.DEFAULT_PAGES_RELATIVE_PATH = exports.NAV_SHELL_RELATIVE_PATH = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const gray_matter_1 = __importDefault(require("gray-matter"));
 const path_1 = __importDefault(require("path"));
+const markdown_1 = require("../utils/markdown");
 const menu_shell_1 = require("../utils/menu-shell");
 const logger_1 = require("../utils/logger");
+const pages_1 = require("../utils/pages");
 /**
  * Relative path (within the staged Next app) of the baked navigation shell. The docs read API
  * (`pages/api/docs/nav.json.ts`) imports this statically so it is bundled into the route chunk and
@@ -27,21 +28,13 @@ const logger_1 = require("../utils/logger");
 exports.NAV_SHELL_RELATIVE_PATH = path_1.default.join('generated', 'nav-shell.json');
 /** Baked package-default markdown used as the registry catch-all's runtime fallback. */
 exports.DEFAULT_PAGES_RELATIVE_PATH = path_1.default.join('generated', 'default-pages.json');
-/** Recursively collect package docs (except dedicated index routes) by their catch-all id. */
-const collectDefaultPages = (root, relativeParts = []) => {
-    if (!fs_extra_1.default.existsSync(root))
-        return {};
+/** Collect package defaults for registry fallbacks, including the dedicated root home page. */
+const collectDefaultPages = (root) => {
     const pages = {};
-    for (const entry of fs_extra_1.default.readdirSync(root)) {
-        const absolutePath = path_1.default.join(root, entry);
-        if (fs_extra_1.default.lstatSync(absolutePath).isDirectory()) {
-            Object.assign(pages, collectDefaultPages(absolutePath, [...relativeParts, entry]));
-        }
-        else if (entry.endsWith('.md') && entry !== 'index.md') {
-            const id = [...relativeParts, entry.replace(/\.md$/, '')].join('/');
-            const { data, content } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(absolutePath, 'utf8'));
-            pages[id] = { metadata: data, content };
-        }
+    for (const segments of (0, pages_1.collectPageSlugSegments)(root, { includeRootIndex: true })) {
+        const id = segments.join('/');
+        const { data, content } = (0, markdown_1.parseMarkdown)(fs_extra_1.default.readFileSync(path_1.default.resolve(root, `${id}.md`), 'utf8'));
+        pages[id] = { metadata: data, content };
     }
     return pages;
 };

package/dist/app-builder/vercel-output.js

@@ -15,6 +15,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeRegistryVercelOutput = exports.writeStaticVercelOutput = exports.getVercelOutputPath = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const content_kinds_1 = require("../registry/content-kinds");
 const logger_1 = require("../utils/logger");
 /**
  * Vercel Build Output API layout.
@@ -151,9 +152,8 @@ module.exports = async (req, res) => {
  *
  * Routes materialized from the mutable docs catch-all also appear in `routes` when package defaults
  * are prerendered. They are identified by `srcRoute` and deliberately left behind the function so a
- * published DB record can override the fallback. Other `fallback:'blocking'` dynamic routes are
- * absent and naturally reach the function. Immutable pages — e.g. the header's `<Link href="/">`
- * prefetch of `/_next/data/<buildId>/index.json` — are served straight from the CDN.
+ * published DB record can override the fallback. The root page is also mutable and stays behind the
+ * function. Other `fallback:'blocking'` dynamic routes are absent and naturally reach the function.
  *
  * No-op when nothing is prerendered (empty `routes`). Paths are emitted base-path-less, matching the
  * existing `_next/static` copy and the registry route table.
@@ -173,7 +173,7 @@ const copyPrerenderedStaticPages = (appPath, staticOutDir) => __awaiter(void 0,
     for (const [route, routeConfig] of Object.entries(routes)) {
         // A static copy would win at the Build Output API filesystem route and permanently hide a
         // published override (and its on-demand revalidation) from the registry function.
-        if (routeConfig.srcRoute === MUTABLE_REGISTRY_PAGE_SRC_ROUTE) {
+        if (route === content_kinds_1.HOME_PAGE_PATH || routeConfig.srcRoute === MUTABLE_REGISTRY_PAGE_SRC_ROUTE) {
             continue;
         }
         // `.next/server/pages/<rel>.{html,json}` — `/` maps to `index`, nested routes keep their path.

package/dist/cli/make.js

@@ -93,13 +93,13 @@ const makePage = (handoff, name, parent) => __awaiter(void 0, void 0, void 0, fu
         logger_1.Logger.error(`Page name must be set`);
         return;
     }
-    if (!/^[a-z0-9]+$/i.test(name)) {
+    if (!/^[a-z0-9_-]+$/i.test(name)) {
         logger_1.Logger.error(`Page name must be alphanumeric and may contain dashes or underscores`);
         return;
     }
     let workingPath, sourcePath, templatePath;
     if (parent) {
-        if (!/^[a-z0-9]+$/i.test(parent)) {
+        if (!/^[a-z0-9_-]+$/i.test(parent)) {
             logger_1.Logger.error(`Parent name must be alphanumeric and may contain dashes or underscores`);
             return;
         }

package/dist/cli.js

@@ -1,5 +1,14 @@
 #! /usr/bin/env node
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -7,6 +16,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const helpers_1 = require("yargs/helpers");
 const yargs_1 = __importDefault(require("yargs/yargs"));
 const commands_1 = require("./commands");
+const config_1 = require("./config");
+const logger_1 = require("./utils/logger");
 class HandoffCliError extends Error {
     constructor(message) {
         // 'Error' breaks prototype chain here
@@ -32,18 +43,39 @@ const cliError = function (msg, exitCode = 1) {
     err.exitCode = exitCode;
     throw err;
 };
-const run = () => {
+const run = () => __awaiter(void 0, void 0, void 0, function* () {
     try {
         const yargsInstance = (0, yargs_1.default)((0, helpers_1.hideBin)(process.argv));
         commands_1.commands.forEach((command) => {
             yargsInstance.command(command);
         });
-        yargsInstance.help().version(showVersion()).strict().parse();
+        yargsInstance.fail((msg, error, instance) => {
+            // A bad `-c` is the user's to fix: one actionable line, no usage dump and no stack trace.
+            if (error instanceof config_1.HandoffConfigError) {
+                logger_1.Logger.error(error.message);
+                process.exit(1);
+            }
+            // Anything else unexpected keeps its stack; usage errors keep yargs' help-then-message output.
+            if (error) {
+                throw error;
+            }
+            instance.showHelp();
+            logger_1.Logger.error(msg);
+            process.exit(1);
+        });
+        // Awaited so a rejected async handler reaches the failure handling above.
+        yield yargsInstance.help().version(showVersion()).strict().parseAsync();
     }
     catch (e) {
-        if (e.message.indexOf('Unknown or unexpected option') === -1)
+        const message = e instanceof Error ? e.message : String(e);
+        if (message.indexOf('Unknown or unexpected option') === -1)
             throw e;
-        return cliError(e.message, 2);
+        return cliError(message, 2);
     }
-};
-run();
+});
+run().catch((error) => {
+    // User-facing failures are already reported above, so anything landing here is unexpected and
+    // keeps its stack trace.
+    console.error(error);
+    process.exit(1);
+});

package/dist/commands/build/app.js

@@ -8,11 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../../"));
 const utils_1 = require("../utils");
 const command = {
     command: 'build:app',
@@ -26,7 +22,7 @@ const command = {
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
         var _a;
-        const handoff = new __1.default(args.debug, args.force);
+        const handoff = (0, utils_1.createHandoff)(args);
         yield handoff.build('static', (_a = args.skipComponents) !== null && _a !== void 0 ? _a : false);
     }),
 };

package/dist/commands/build/components.js

@@ -8,11 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../.."));
 const utils_1 = require("../utils");
 const command = {
     command: 'build:components [component]',
@@ -24,7 +20,7 @@ const command = {
         });
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
-        const handoff = new __1.default(args.debug, args.force);
+        const handoff = (0, utils_1.createHandoff)(args);
         yield handoff.component(args.component);
     }),
 };

package/dist/commands/build/index.js

@@ -8,11 +8,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../../"));
 const app_builder_1 = require("../../app-builder");
 const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
@@ -47,7 +43,7 @@ const command = {
     },
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
         var _a, _b;
-        const handoff = new __1.default(args.debug, args.force);
+        const handoff = (0, utils_1.createHandoff)(args);
         try {
             yield handoff.build((_a = args.target) !== null && _a !== void 0 ? _a : app_builder_1.DEFAULT_BUILD_TARGET, (_b = args.skipComponents) !== null && _b !== void 0 ? _b : false, args.package);
         }

package/dist/commands/checkout/index.d.ts

@@ -1,24 +1,27 @@
 import { CommandModule } from 'yargs';
 import { SharedArgs } from '../types';
-import { RegistryEntityKind } from '../utils';
+import { RegistryTargetKind } from '../utils';
 export interface CheckoutArgs extends SharedArgs {
-    type: RegistryEntityKind;
-    id?: string;
+    type: RegistryTargetKind;
+    id?: string[];
 }
 /**
- * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
- * into this workspace, writing their source files in standard authoring form and synthesizing local
- * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
- * that kind.
+ * `handoff-app checkout <components|patterns|pages> [id...]` pulls entities from the connected
+ * registry into this workspace, writing their source files in standard authoring form and
+ * synthesizing local declarations. Pass ids to pull only those entities, or omit them for every
+ * published entity of that kind.
  *
- * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
- * this workspace: reconstruct `tokens.json` and restore the generated token files.
+ * `handoff-app checkout tokens [setId...]` pulls every published token set, or only the named ones,
+ * reconstructing `tokens.json` and restoring the generated token files.
+ *
+ * `handoff-app checkout assets [collection...]` pulls every published asset collection, or only the
+ * named ones, recreating the standard asset files, sprite/manifest and archives.
+ *
+ * `handoff-app checkout all` runs every kind in the same order publish uses.
  *
- * `handoff-app checkout assets [collection]` pulls every published asset collection (or only the
- * named one) into this workspace, recreating the standard asset files, sprite/manifest, and archives.
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files requires `--force` or an interactive
- * confirmation.
+ * confirmation; `--dry-run` lists what would be written and changes nothing.
  */
 declare const command: CommandModule<{}, CheckoutArgs>;
 export default command;

package/dist/commands/checkout/index.js

@@ -1,67 +1,28 @@
 "use strict";
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const __1 = __importDefault(require("../../"));
-const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
 /**
- * `handoff-app checkout <components|patterns|pages> [id]` pulls entities from the connected registry
- * into this workspace, writing their source files in standard authoring form and synthesizing local
- * declarations. Pass an `id` to pull that one entity, or omit it to pull every published entity of
- * that kind.
+ * `handoff-app checkout <components|patterns|pages> [id...]` pulls entities from the connected
+ * registry into this workspace, writing their source files in standard authoring form and
+ * synthesizing local declarations. Pass ids to pull only those entities, or omit them for every
+ * published entity of that kind.
+ *
+ * `handoff-app checkout tokens [setId...]` pulls every published token set, or only the named ones,
+ * reconstructing `tokens.json` and restoring the generated token files.
+ *
+ * `handoff-app checkout assets [collection...]` pulls every published asset collection, or only the
+ * named ones, recreating the standard asset files, sprite/manifest and archives.
  *
- * `handoff-app checkout tokens [setId]` — pull every published token set (or only the named set) into
- * this workspace: reconstruct `tokens.json` and restore the generated token files.
+ * `handoff-app checkout all` runs every kind in the same order publish uses.
  *
- * `handoff-app checkout assets [collection]` pulls every published asset collection (or only the
- * named one) into this workspace, recreating the standard asset files, sprite/manifest, and archives.
  * Available only from a connected workspace (`runtime.mode: workspace` + a configured
  * `registryConnection`). Overwriting existing local files requires `--force` or an interactive
- * confirmation.
+ * confirmation; `--dry-run` lists what would be written and changes nothing.
  */
 const command = {
-    command: 'checkout <type> [id]',
+    command: 'checkout <type> [id..]',
     describe: 'Pull components, patterns, pages, design tokens, or assets from the connected registry into this workspace',
-    builder: (yargs) => {
-        return (0, utils_1.getSharedOptions)(yargs)
-            .positional('type', {
-            describe: 'The kind of entity to checkout',
-            choices: utils_1.REGISTRY_ENTITY_KINDS,
-            type: 'string',
-        })
-            .positional('id', {
-            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); omit to checkout all of that kind',
-            type: 'string',
-        });
-    },
-    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
-        const handoff = new __1.default(args.debug, args.force);
-        try {
-            if (args.type === 'tokens') {
-                yield handoff.checkoutTokens(args.id);
-                return;
-            }
-            if (args.type === 'assets') {
-                yield handoff.checkoutAssets(args.id);
-                return;
-            }
-            yield handoff.checkout(utils_1.ENTITY_WIRE_KIND[args.type], args.id);
-        }
-        catch (error) {
-            logger_1.Logger.error(error instanceof Error ? error.message : String(error));
-            process.exitCode = 1;
-        }
-    }),
+    builder: (yargs) => (0, utils_1.withTargetPositionals)((0, utils_1.getCheckoutOptions)(yargs), 'checkout'),
+    handler: (args) => (0, utils_1.runRegistryCommand)(args, (handoff) => (0, utils_1.runTarget)(handoff, args.type, args.id, 'checkout')),
 };
 exports.default = command;

package/dist/commands/compat/deprecations.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Deprecation notices for the documented-but-superseded CLI surface.
+ *
+ * Messaging only: no publish, checkout or config behavior lives in this directory. Notices go through
+ * {@link Logger.warn} so `HANDOFF_LOG_LEVEL=error` silences them in CI, where the operator has
+ * already accepted the older form.
+ *
+ * Call these from inside `runRegistryCommand`'s callback, never before it. `Logger` reads
+ * `HANDOFF_LOG_LEVEL` when the `Handoff` instance is constructed, so a notice emitted earlier prints
+ * at the default level and ignores the configured one.
+ */
+/** Announce that a command is on its way out and name the canonical form to move to. */
+export declare const warnDeprecatedCommand: (invoked: string, canonical: string) => void;
+/**
+ * A documented option we cannot honor, and why. Declared rather than left to `.strict()` so a command
+ * copied from the docs runs and explains itself instead of failing with "Unknown argument".
+ */
+interface UnsupportedOption {
+    /** yargs option key, camelCased as yargs delivers it. */
+    key: string;
+    /** How the option is written on the command line, for the warning text. */
+    flag: string;
+    /** yargs value type; only `-m, --message` carries a value. */
+    type?: 'boolean' | 'string';
+    /** Short flag, where the docs give one. */
+    alias?: string;
+    reason: string;
+}
+/** Options documented for `push` itself. */
+export declare const UNSUPPORTED_PUSH_OPTIONS: readonly UnsupportedOption[];
+/** Options documented for `push:tokens`. */
+export declare const UNSUPPORTED_PUSH_TOKENS_OPTIONS: readonly UnsupportedOption[];
+/** `push:all` steps documented for subsystems we do not have. */
+export declare const UNSUPPORTED_PUSH_ALL_OPTIONS: readonly UnsupportedOption[];
+/** Declare unsupported options as hidden yargs booleans so `.strict()` accepts them. */
+export declare const hiddenOptions: (options: readonly UnsupportedOption[]) => {
+    [k: string]: {
+        alias?: string;
+        type: "string" | "boolean";
+        hidden: boolean;
+        describe: string;
+    };
+};
+/** Warn about every unsupported option present on the command line, then carry on. */
+export declare const warnUnsupportedOptions: (args: Record<string, unknown>, options: readonly UnsupportedOption[]) => void;
+export {};

package/dist/commands/compat/deprecations.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Deprecation notices for the documented-but-superseded CLI surface.
+ *
+ * Messaging only: no publish, checkout or config behavior lives in this directory. Notices go through
+ * {@link Logger.warn} so `HANDOFF_LOG_LEVEL=error` silences them in CI, where the operator has
+ * already accepted the older form.
+ *
+ * Call these from inside `runRegistryCommand`'s callback, never before it. `Logger` reads
+ * `HANDOFF_LOG_LEVEL` when the `Handoff` instance is constructed, so a notice emitted earlier prints
+ * at the default level and ignores the configured one.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warnUnsupportedOptions = exports.hiddenOptions = exports.UNSUPPORTED_PUSH_ALL_OPTIONS = exports.UNSUPPORTED_PUSH_TOKENS_OPTIONS = exports.UNSUPPORTED_PUSH_OPTIONS = exports.warnDeprecatedCommand = void 0;
+const logger_1 = require("../../utils/logger");
+/** Announce that a command is on its way out and name the canonical form to move to. */
+const warnDeprecatedCommand = (invoked, canonical) => {
+    logger_1.Logger.warn(`\`handoff-app ${invoked}\` is deprecated and will be removed in a future release; use \`handoff-app ${canonical}\` instead.`);
+};
+exports.warnDeprecatedCommand = warnDeprecatedCommand;
+/** Options documented for `push` itself. */
+exports.UNSUPPORTED_PUSH_OPTIONS = [
+    {
+        key: 'metadataOnly',
+        flag: '--metadata-only',
+        reason: 'a publish replaces an entity\'s files and artifacts as one package, so a metadata-only upload would delete them',
+    },
+    { key: 'message', flag: '-m, --message', type: 'string', alias: 'm', reason: 'there is no change history to annotate' },
+];
+/** Options documented for `push:tokens`. */
+exports.UNSUPPORTED_PUSH_TOKENS_OPTIONS = [
+    { key: 'skipFigma', flag: '--skip-figma', reason: 'rebuilding tokens without a Figma request is not implemented yet' },
+    { key: 'skipDtcg', flag: '--skip-dtcg', reason: 'there is no DTCG dist step in this pipeline' },
+];
+/** `push:all` steps documented for subsystems we do not have. */
+exports.UNSUPPORTED_PUSH_ALL_OPTIONS = [
+    { key: 'skipBuild', flag: '--skip-build', reason: 'use --no-build, which applies to the whole run' },
+    ...['config', 'theme', 'navigation', 'dtcg', 'icons', 'logos', 'fonts', 'figma-fills', 'image-slots', 'design-md'].map((step) => ({
+        key: `skip${step.replace(/(^|-)([a-z])/g, (_match, _dash, letter) => letter.toUpperCase())}`,
+        flag: `--skip-${step}`,
+        reason: 'this implementation has no such publish step',
+    })),
+    { key: 'message', flag: '-m, --message', type: 'string', alias: 'm', reason: 'there is no change history to annotate' },
+];
+/** Declare unsupported options as hidden yargs booleans so `.strict()` accepts them. */
+const hiddenOptions = (options) => Object.fromEntries(options.map((option) => {
+    var _a;
+    return [
+        option.key,
+        Object.assign({ type: (_a = option.type) !== null && _a !== void 0 ? _a : 'boolean', hidden: true, describe: option.reason }, (option.alias ? { alias: option.alias } : {})),
+    ];
+}));
+exports.hiddenOptions = hiddenOptions;
+/** Warn about every unsupported option present on the command line, then carry on. */
+const warnUnsupportedOptions = (args, options) => {
+    for (const option of options) {
+        if (args[option.key] !== undefined && args[option.key] !== false) {
+            logger_1.Logger.warn(`${option.flag} is ignored: ${option.reason}.`);
+        }
+    }
+};
+exports.warnUnsupportedOptions = warnUnsupportedOptions;

package/dist/commands/compat/push-args.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Translation from the documented `push` / `pull` argument shape to canonical publish targets.
+ *
+ * The published CLI reference addresses content with selective flags (`--components <ids>`) and an
+ * implied "everything" default, while we address it positionally (`publish <type> [id...]`). These
+ * are pure functions that convert one into the other; the publishing itself is done by
+ * {@link Handoff.publishAll}, so no orchestration lives here.
+ */
+import { type RegistryEntityKind } from '../../registry/content-kinds';
+import type { RegistryTargetKind } from '../utils';
+import type { ContentTarget } from '../../index';
+/** The documented `push` / `pull` arguments read here. */
+export interface CompatTargetArgs {
+    type?: RegistryTargetKind;
+    id?: string[];
+    components?: string[];
+    patterns?: string[];
+    pages?: string[];
+}
+/** The documented `push:all` skip flags that map onto a real content kind. */
+export interface CompatSkipArgs {
+    skipTokens?: boolean;
+    skipAssets?: boolean;
+    skipComponents?: boolean;
+    skipPatterns?: boolean;
+    skipPages?: boolean;
+}
+/** The documented `push:assets` skip flags. */
+export interface CompatAssetSkipArgs {
+    skipIcons?: boolean;
+    skipLogos?: boolean;
+}
+/**
+ * Resolve what a documented `push` / `pull` invocation targets, in precedence order:
+ *
+ * 1. selective flags (`--components a b --pages intro`), the documented way to narrow a run;
+ * 2. a positional kind, matching our own `publish <type> [id...]`;
+ * 3. nothing, which the docs define as pages plus component and pattern declarations.
+ */
+export declare const resolveCompatTargets: (args: CompatTargetArgs) => ContentTarget[];
+/** Resolve the kinds a documented `push:all` should run, honoring its `--skip-<kind>` flags. */
+export declare const resolveCompatAllKinds: (args: CompatSkipArgs) => RegistryEntityKind[];
+/**
+ * Resolve the asset collections a documented `push:assets` should publish. Returns `undefined` when
+ * nothing is skipped, so the canonical path still discovers collections itself instead of being
+ * pinned to the compile-time list.
+ */
+export declare const resolveCompatAssetSelection: (args: CompatAssetSkipArgs, collection?: string) => string[] | undefined;

package/dist/commands/compat/push-args.js

@@ -0,0 +1,73 @@
+"use strict";
+/**
+ * Translation from the documented `push` / `pull` argument shape to canonical publish targets.
+ *
+ * The published CLI reference addresses content with selective flags (`--components <ids>`) and an
+ * implied "everything" default, while we address it positionally (`publish <type> [id...]`). These
+ * are pure functions that convert one into the other; the publishing itself is done by
+ * {@link Handoff.publishAll}, so no orchestration lives here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveCompatAssetSelection = exports.resolveCompatAllKinds = exports.resolveCompatTargets = void 0;
+const sets_1 = require("../../registry/assets/sets");
+const content_kinds_1 = require("../../registry/content-kinds");
+const logger_1 = require("../../utils/logger");
+/** Selective flag → the kind it narrows. Ordered so a mixed request still runs in dependency order. */
+const SELECTIVE_FLAGS = [
+    { flag: 'components', kind: 'components' },
+    { flag: 'patterns', kind: 'patterns' },
+    { flag: 'pages', kind: 'pages' },
+];
+/** Skip flag → the kind it removes. */
+const SKIP_FLAGS = {
+    tokens: 'skipTokens',
+    assets: 'skipAssets',
+    components: 'skipComponents',
+    patterns: 'skipPatterns',
+    pages: 'skipPages',
+};
+/**
+ * Resolve what a documented `push` / `pull` invocation targets, in precedence order:
+ *
+ * 1. selective flags (`--components a b --pages intro`), the documented way to narrow a run;
+ * 2. a positional kind, matching our own `publish <type> [id...]`;
+ * 3. nothing, which the docs define as pages plus component and pattern declarations.
+ */
+const resolveCompatTargets = (args) => {
+    var _a;
+    const selective = SELECTIVE_FLAGS.filter(({ flag }) => { var _a; return (_a = args[flag]) === null || _a === void 0 ? void 0 : _a.length; }).map(({ flag, kind }) => ({
+        kind,
+        ids: args[flag],
+    }));
+    if (selective.length > 0) {
+        if (args.type) {
+            logger_1.Logger.warn(`Ignoring the "${args.type}" argument because selective flags were also given.`);
+        }
+        return selective;
+    }
+    // `all` is the canonical every-kind form; expand it here so `push all` behaves like `publish all`.
+    if (args.type === 'all') {
+        return [...content_kinds_1.ALL_KIND_ORDER];
+    }
+    if (args.type) {
+        return [{ kind: args.type, ids: ((_a = args.id) === null || _a === void 0 ? void 0 : _a.length) ? args.id : undefined }];
+    }
+    return [...content_kinds_1.ENTITY_KIND_ORDER];
+};
+exports.resolveCompatTargets = resolveCompatTargets;
+/** Resolve the kinds a documented `push:all` should run, honoring its `--skip-<kind>` flags. */
+const resolveCompatAllKinds = (args) => content_kinds_1.ALL_KIND_ORDER.filter((kind) => !args[SKIP_FLAGS[kind]]);
+exports.resolveCompatAllKinds = resolveCompatAllKinds;
+/**
+ * Resolve the asset collections a documented `push:assets` should publish. Returns `undefined` when
+ * nothing is skipped, so the canonical path still discovers collections itself instead of being
+ * pinned to the compile-time list.
+ */
+const resolveCompatAssetSelection = (args, collection) => {
+    if (collection) {
+        return [collection];
+    }
+    const skipped = new Set([...(args.skipIcons ? ['icons'] : []), ...(args.skipLogos ? ['logos'] : [])]);
+    return skipped.size > 0 ? sets_1.ASSET_COLLECTIONS.filter((name) => !skipped.has(name)) : undefined;
+};
+exports.resolveCompatAssetSelection = resolveCompatAssetSelection;