@microsoft/managed-apps-cli 0.6.1 → 0.8.0

package/dist/Middletier/FunctionsBundler.js

@@ -0,0 +1,165 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import * as path from 'node:path';
+import { AppError } from '../Errors/CliError.js';
+/**
+ * Maps the browser-SDK specifiers that generated/customer code imports to the
+ * workerd-SDK specifiers that survive into the bundled output. esbuild uses
+ * this map for two things:
+ *   - `alias`: rewrites every key to its value during resolution.
+ *   - `external`: marks every value as external so the import statement is
+ *     left intact in the bundle and resolved at workerd instantiation time.
+ *
+ * The allowlist plugin also derives from this map (see {@link ALLOWED_PACKAGES}),
+ * so this is the single source of truth — the three derived uses stay in sync
+ * automatically.
+ */
+const MIDDLETIER_PACKAGE_ALIAS_MAP = {
+    '@microsoft/managed-apps/data': '@microsoft/managed-apps-functions/data',
+};
+/**
+ * Specifier the externalized `generated/dataSources` import gets rewritten to.
+ * The functions-runtime registers a workerd `json` module under this name with
+ * the pack's `dataSources.json` as its content, so every customer bundle reads
+ * the data sources from a single shared file instead of inlining a per-bundle
+ * copy of the ~16KB config blob.
+ */
+const DATA_SOURCES_MODULE = '@config/dataSources';
+/**
+ * Bundles each discovered function entry point to ESM JavaScript using esbuild.
+ * Returns a Map keyed by the function's `relPath` (same key as
+ * {@link DiscoveredFunction.relPath}) with the bundled JS source as the value.
+ *
+ * esbuild is imported dynamically (`await import('esbuild')`) so the CLI can be
+ * shipped into environments that mark esbuild `--external` and supply their own.
+ */
+export async function bundleFunctionsAsync(args) {
+    const { projectRoot, functions } = args;
+    if (functions.length === 0)
+        return new Map();
+    // `.catch` so a missing-esbuild error gets a clear, actionable message
+    // instead of the raw module-resolution failure surfacing to the user.
+    const esbuild = await import('esbuild').catch((err) => {
+        throw new AppError(`esbuild is required to pack functions but could not be loaded: ${err.message}`);
+    });
+    // esbuild's Go worker pool parallelises within a single `build()`, but
+    // running per-file builds in parallel still lets us overlap plugin
+    // callbacks and JS-side work. esbuild self-bounds concurrency internally,
+    // so we don't need our own semaphore.
+    const entries = await Promise.all(functions.map(async (fn) => {
+        const result = await esbuild.build({
+            entryPoints: [fn.absPath],
+            bundle: true,
+            write: false,
+            format: 'esm',
+            platform: 'neutral',
+            target: 'es2022',
+            external: [...Object.values(MIDDLETIER_PACKAGE_ALIAS_MAP), DATA_SOURCES_MODULE],
+            alias: MIDDLETIER_PACKAGE_ALIAS_MAP,
+            // Plugin order matters — `dataSourcesPlugin` returns first so the
+            // allowlist never sees the externalised `@config/dataSources` rewrite
+            // and the resolved-path lookup for `generated/dataSources.ts` short-
+            // circuits before the allowlist would have admitted it via the
+            // `generated/` rule.
+            plugins: [dataSourcesPlugin(projectRoot), allowlistPlugin(projectRoot)],
+            logLevel: 'silent',
+        });
+        const output = result.outputFiles?.[0];
+        if (!output) {
+            throw new AppError(`Failed to bundle function ${fn.relPath}: esbuild produced no output`);
+        }
+        return [fn.relPath, output.text];
+    }));
+    return new Map(entries);
+}
+/**
+ * esbuild `onResolve` plugin that intercepts the codegen-emitted
+ * `import dataSources from '../dataSources'` (or any path resolving to
+ * `<projectRoot>/generated/dataSources.<ext>`) and rewrites it to the
+ * canonical {@link DATA_SOURCES_MODULE} specifier, marked external. The
+ * functions-runtime supplies the resolved value at workerd config time as a
+ * `json` module embedded from the pack's `dataSources.json`, so a single
+ * shared copy is read by every function instead of the ~16KB config map
+ * being inlined into each bundle.
+ *
+ * Matching is by resolved file path (not import-specifier string) so codegen
+ * layout changes that move the file or alter the relative-path shape don't
+ * break the substitution.
+ */
+function dataSourcesPlugin(projectRoot) {
+    // Codegen always emits `generated/dataSources.ts`; specifier is extensionless
+    // (`../dataSources`), so we resolve the relative path and tack on `.ts` to
+    // get the candidate filesystem location, then compare.
+    const target = path.resolve(projectRoot, 'generated/dataSources.ts');
+    return {
+        name: 'external-data-sources',
+        setup(build) {
+            build.onResolve({ filter: /(^|\/)dataSources$/ }, (args) => {
+                if (!args.path.startsWith('.'))
+                    return null;
+                const resolved = path.resolve(path.dirname(args.importer), args.path) + '.ts';
+                if (resolved !== target)
+                    return null;
+                return { path: DATA_SOURCES_MODULE, external: true };
+            });
+        },
+    };
+}
+/**
+ * esbuild `onResolve` plugin that fails the build when customer code imports
+ * anything outside the allowlist. Two categories pass:
+ *
+ * - Relative imports that resolve inside the project's `generated/` folder.
+ * - Bare specifiers exactly matching an entry in {@link ALLOWED_PACKAGES}.
+ *
+ * esbuild applies `alias` substitution *after* `onResolve` plugins run, so the
+ * incoming `args.path` is always the pre-alias specifier.
+ */
+function allowlistPlugin(projectRoot) {
+    const generatedDir = path.resolve(projectRoot, 'generated');
+    return {
+        name: 'allowlist-imports',
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, (args) => {
+                if (args.kind === 'entry-point')
+                    return null;
+                if (args.path.startsWith('.')) {
+                    const resolved = path.resolve(path.dirname(args.importer), args.path);
+                    if (resolved.startsWith(generatedDir + path.sep)) {
+                        return null;
+                    }
+                    return {
+                        errors: [
+                            {
+                                text: `Relative import '${args.path}' is outside the allowed 'generated/' folder`,
+                            },
+                        ],
+                    };
+                }
+                /**
+                 * The exact module specifiers customer/generated code is allowed to import
+                 * from outside the project's `generated/` folder. Anything else — arbitrary
+                 * npm packages, `node:*` built-ins, other scopes, deeper subpaths — is a
+                 * build error.
+                 *
+                 * esbuild applies `alias` substitution *after* `onResolve` plugins run, so the
+                 * allowlist matches the pre-alias specifier (the map key), not the post-alias
+                 * target.
+                 */
+                if (MIDDLETIER_PACKAGE_ALIAS_MAP[args.path])
+                    return null;
+                return {
+                    errors: [
+                        {
+                            text: `Import '${args.path}' is not on the allowlist. Allowed: relative imports into 'generated/' and ${Object.keys(MIDDLETIER_PACKAGE_ALIAS_MAP)
+                                .map((p) => `'${p}'`)
+                                .join(', ')}.`,
+                        },
+                    ],
+                };
+            });
+        },
+    };
+}
+//# sourceMappingURL=FunctionsBundler.js.map

package/dist/Middletier/FunctionsBundler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionsBundler.js","sourceRoot":"","sources":["../../src/Middletier/FunctionsBundler.ts"],"names":[],"mappings":"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"}

package/dist/Middletier/PackFunctions.d.ts

@@ -0,0 +1,52 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import type { FunctionRoute, FunctionsPackage } from '@microsoft/managed-apps-common/types';
+/** Filename of the functions archive written next to manifest.json. */
+export declare const FUNCTIONS_ARCHIVE_NAME = "functions.zip";
+/** Archive format/compression embedded in the manifest. Standard zip uses DEFLATE. */
+export declare const FUNCTIONS_ARCHIVE_DESCRIPTOR: Omit<FunctionsPackage, 'path'>;
+/** A single `.ts` function discovered under `functions.baseDirectory`. */
+export interface DiscoveredFunction {
+    /** Path relative to `functions.baseDirectory`, with forward slashes. Includes `.ts` suffix. */
+    relPath: string;
+    /** Absolute path to the source file on disk. */
+    absPath: string;
+}
+/**
+ * Recursively walks `baseDirectory` and returns every `.ts` file beneath it.
+ *
+ * The directory must exist; callers are expected to have validated this via
+ * {@link assertFunctionsDirectoryExists}. An existing directory containing no
+ * `.ts` files returns an empty array — that case maps to "skip packing" per the
+ * pack spec, not an error.
+ */
+export declare function discoverFunctionsAsync(baseDirectory: string): Promise<DiscoveredFunction[]>;
+export declare function assertFunctionsDirectoryExists(baseDirectory: string): Promise<void>;
+/**
+ * Builds the `routes` entries for compiled functions. The key is the basename
+ * of `functions.baseDirectory` joined with the function's path relative to
+ * that directory (`.ts` stripped); `path` is the same string with `.js`. Both
+ * mirror the entry's location inside the archive.
+ */
+export declare function buildFunctionRoutes(functions: readonly DiscoveredFunction[], baseDirName: string): Record<string, FunctionRoute>;
+/**
+ * Builds a zip Buffer containing one bundled `.js` per discovered `.ts` source
+ * (mirroring the source layout under `<baseDirName>/`), plus the generated
+ * `manifest.json` and — when present — `dataSources.json`.
+ *
+ * `bundles` is a Map keyed by `DiscoveredFunction.relPath` whose value is the
+ * bundled JS source from {@link bundleFunctionsAsync}. Every discovered function
+ * must have a corresponding bundle; missing entries throw.
+ *
+ * Returning a `Buffer` (vs. streaming to disk) lets callers use `fsp.writeFile`,
+ * which keeps the implementation testable under memfs.
+ */
+export declare function buildFunctionsArchiveAsync(args: {
+    baseDirName: string;
+    functions: readonly DiscoveredFunction[];
+    bundles: ReadonlyMap<string, string>;
+    manifestContent: string;
+    dataSourcesJson: string | undefined;
+}): Promise<Buffer>;
+//# sourceMappingURL=PackFunctions.d.ts.map

package/dist/Middletier/PackFunctions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackFunctions.d.ts","sourceRoot":"","sources":["../../src/Middletier/PackFunctions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAK5F,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD,sFAAsF;AACtF,eAAO,MAAM,4BAA4B,EAAE,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAGvE,CAAC;AAEF,0EAA0E;AAC1E,MAAM,WAAW,kBAAkB;IACjC,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAKjG;AA6BD,wBAAsB,8BAA8B,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,SAAS,kBAAkB,EAAE,EACxC,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAU/B;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACzC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BlB"}

package/dist/Middletier/PackFunctions.js

@@ -0,0 +1,122 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import archiver from 'archiver';
+import { ConfigurationError } from '../Errors/CliError.js';
+/** Filename of the functions archive written next to manifest.json. */
+export const FUNCTIONS_ARCHIVE_NAME = 'functions.zip';
+/** Archive format/compression embedded in the manifest. Standard zip uses DEFLATE. */
+export const FUNCTIONS_ARCHIVE_DESCRIPTOR = {
+    archive: 'zip',
+    compression: 'deflate',
+};
+/**
+ * Recursively walks `baseDirectory` and returns every `.ts` file beneath it.
+ *
+ * The directory must exist; callers are expected to have validated this via
+ * {@link assertFunctionsDirectoryExists}. An existing directory containing no
+ * `.ts` files returns an empty array — that case maps to "skip packing" per the
+ * pack spec, not an error.
+ */
+export async function discoverFunctionsAsync(baseDirectory) {
+    const results = [];
+    await walkAsync(baseDirectory, '', results);
+    results.sort((a, b) => a.relPath.localeCompare(b.relPath));
+    return results;
+}
+async function walkAsync(absDir, relDir, out) {
+    const entries = await fsp.readdir(absDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const entryRel = relDir ? `${relDir}/${entry.name}` : entry.name;
+        const entryAbs = path.join(absDir, entry.name);
+        if (entry.isDirectory()) {
+            await walkAsync(entryAbs, entryRel, out);
+        }
+        else if (entry.isFile() && isFunctionSourceFile(entry.name)) {
+            out.push({ relPath: entryRel, absPath: entryAbs });
+        }
+    }
+}
+/**
+ * `.ts` files that are part of the function surface. Skips type declarations
+ * (`.d.ts` — no runtime) and unit-test files (`.test.ts` / `.spec.ts` — not
+ * functions, and the common JS ecosystem convention is to co-locate them).
+ */
+function isFunctionSourceFile(name) {
+    return (name.endsWith('.ts') &&
+        !name.endsWith('.d.ts') &&
+        !name.endsWith('.test.ts') &&
+        !name.endsWith('.spec.ts'));
+}
+export async function assertFunctionsDirectoryExists(baseDirectory) {
+    let stat;
+    try {
+        stat = await fsp.stat(baseDirectory);
+    }
+    catch {
+        throw new ConfigurationError(`functions.baseDirectory does not exist: ${baseDirectory}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new ConfigurationError(`functions.baseDirectory is not a directory: ${baseDirectory}`);
+    }
+}
+/**
+ * Builds the `routes` entries for compiled functions. The key is the basename
+ * of `functions.baseDirectory` joined with the function's path relative to
+ * that directory (`.ts` stripped); `path` is the same string with `.js`. Both
+ * mirror the entry's location inside the archive.
+ */
+export function buildFunctionRoutes(functions, baseDirName) {
+    const routes = {};
+    for (const fn of functions) {
+        const routeKey = `${baseDirName}/${stripTsExtension(fn.relPath)}`;
+        routes[routeKey] = {
+            type: 'function',
+            path: `${routeKey}.js`,
+        };
+    }
+    return routes;
+}
+function stripTsExtension(relPath) {
+    return relPath.slice(0, -'.ts'.length);
+}
+/**
+ * Builds a zip Buffer containing one bundled `.js` per discovered `.ts` source
+ * (mirroring the source layout under `<baseDirName>/`), plus the generated
+ * `manifest.json` and — when present — `dataSources.json`.
+ *
+ * `bundles` is a Map keyed by `DiscoveredFunction.relPath` whose value is the
+ * bundled JS source from {@link bundleFunctionsAsync}. Every discovered function
+ * must have a corresponding bundle; missing entries throw.
+ *
+ * Returning a `Buffer` (vs. streaming to disk) lets callers use `fsp.writeFile`,
+ * which keeps the implementation testable under memfs.
+ */
+export async function buildFunctionsArchiveAsync(args) {
+    const { baseDirName, functions, bundles, manifestContent, dataSourcesJson } = args;
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        const archive = archiver('zip', { zlib: { level: 9 } });
+        archive.on('data', (chunk) => chunks.push(chunk));
+        archive.on('warning', reject);
+        archive.on('error', reject);
+        archive.on('end', () => resolve(Buffer.concat(chunks)));
+        for (const fn of functions) {
+            const bundled = bundles.get(fn.relPath);
+            if (bundled === undefined) {
+                reject(new Error(`Missing bundled output for function ${fn.relPath}`));
+                return;
+            }
+            const routeKey = stripTsExtension(fn.relPath);
+            archive.append(bundled, { name: `${baseDirName}/${routeKey}.js` });
+        }
+        archive.append(manifestContent, { name: 'manifest.json' });
+        if (dataSourcesJson !== undefined) {
+            archive.append(dataSourcesJson, { name: 'dataSources.json' });
+        }
+        void archive.finalize();
+    });
+}
+//# sourceMappingURL=PackFunctions.js.map

package/dist/Middletier/PackFunctions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PackFunctions.js","sourceRoot":"","sources":["../../src/Middletier/PackFunctions.ts"],"names":[],"mappings":"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"}

package/dist/Types/Cli.types.d.ts

@@ -4,13 +4,54 @@
 import type { AppConfig } from '@microsoft/managed-apps-common/config';
 import type { Region } from '@microsoft/managed-apps-common/services';
 import type { CliFS } from '../FS/CliFs.js';
+export interface CachedAccount {
+    /** MSAL home account ID (`<oid>.<tid>`). Stable across email changes; the canonical key. */
+    homeAccountId: string;
+    /** UPN / email — what we show to the user. */
+    username: string;
+    /** True if this is the account currently used by silent token acquisition. */
+    isActive: boolean;
+}
+/**
+ * Acquires access tokens for authenticated CLI calls. Every auth mode (interactive MSAL,
+ * service principal, HTTP forward) implements this — it's the lowest common denominator.
+ */
 export interface IAuthenticationProvider {
     initAsync(region: Region): Promise<void>;
     getAccessTokenForResource(resource: string, loginHint?: string): Promise<string>;
     getUserTenantId(): string | undefined;
-    /** Returns the cached account email without triggering interactive login. */
+    /** Returns the active cached account email without triggering interactive login. */
     getCachedAccountAsync(): Promise<string | undefined>;
 }
+/**
+ * Manages the local cache of signed-in accounts: list, switch, remove, add. Only the
+ * interactive MSAL provider supports this. Service principal and HTTP forward modes don't
+ * have a "cached account" concept, so they don't implement this interface and the
+ * `auth login`/`logout`/`status`/`switch` verbs refuse to run in those modes.
+ */
+export interface IAccountManager {
+    /** Returns every cached account, marking which one is currently active. */
+    listCachedAccountsAsync(): Promise<CachedAccount[]>;
+    /**
+     * Marks `accountKey` (a username or homeAccountId) as the active account.
+     * Throws if no cached account matches. Returns the resolved account.
+     */
+    setActiveAccountAsync(accountKey: string): Promise<CachedAccount>;
+    /**
+     * Forces an interactive browser sign-in for `resource`. Used by `auth login` so users
+     * can add a new account even when one is already cached. Writes the signed-in account
+     * as the active one.
+     */
+    loginInteractiveAsync(resource: string, loginHint?: string): Promise<CachedAccount>;
+    /**
+     * Removes every cached account and the active-account pointer. Backs `auth logout`.
+     * Routing through the account manager (rather than `fs.rmSync` directly in the verb)
+     * lets non-interactive auth modes refuse the call uniformly via the standard
+     * `getAccountManager()` UsageError. Returns `true` when something was cleared and
+     * `false` when no cached state existed.
+     */
+    clearCacheAsync(): Promise<boolean>;
+}
 export type CliSettings = {
     source: 'pac-cli' | 'standalone';
     interactive: boolean;

package/dist/Types/Cli.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Cli.types.d.ts","sourceRoot":"","sources":["../../src/Types/Cli.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AAEtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjF,eAAe,IAAI,MAAM,GAAG,SAAS,CAAC;IACtC,6EAA6E;IAC7E,qBAAqB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACtD;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,SAAS,GAAG,YAAY,CAAC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC"}
+{"version":3,"file":"Cli.types.d.ts","sourceRoot":"","sources":["../../src/Types/Cli.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AACvE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yCAAyC,CAAC;AAEtE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,WAAW,aAAa;IAC5B,4FAA4F;IAC5F,aAAa,EAAE,MAAM,CAAC;IACtB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACjF,eAAe,IAAI,MAAM,GAAG,SAAS,CAAC;IACtC,oFAAoF;IACpF,qBAAqB,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,uBAAuB,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACpD;;;OAGG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAClE;;;;OAIG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpF;;;;;;OAMG;IACH,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,SAAS,GAAG,YAAY,CAAC;IACjC,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,cAAc,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC"}

package/dist/Types/Command.types.d.ts

@@ -12,15 +12,26 @@ export interface LeafCommandDef {
     handler: CommandHandler;
 }
 /**
- * A typed verb group where the third token selects the subcommand type.
- * e.g. `app add table` — 'add' is the verb, 'table' is the type.
+ * A typed verb group whose next token selects a subcommand. Commands within
+ * a typed verb may themselves be typed verbs, allowing arbitrarily deep
+ * nesting (e.g. `app share link create` — `share` is a typed verb, `link` is
+ * a nested typed verb, `create` is the leaf).
+ *
+ * A typed verb MAY also carry its own `handler` + `@helpText` to support
+ * "hybrid" verbs that accept a positional argument when the next token does
+ * not match a known subcommand. Example: `app share <principals>` (parent
+ * handler) coexisting with `app share link create` (nested subcommand).
  */
 export interface TypedVerbDef {
     typed: true;
-    commands: Record<string, LeafCommandDef>;
+    '@helpText'?: string;
+    handler?: CommandHandler;
+    commands: Record<string, LeafCommandDef | TypedVerbDef>;
 }
 /** Type guard — narrows a verb entry to TypedVerbDef. */
 export declare function isTypedVerbDef(entry: LeafCommandDef | TypedVerbDef): entry is TypedVerbDef;
+/** Narrows to a hybrid TypedVerbDef that also carries a parent handler. */
+export declare function hasParentHandler(entry: TypedVerbDef): entry is TypedVerbDef & Required<Pick<TypedVerbDef, 'handler' | '@helpText'>>;
 /** A noun group with its description and command map. */
 export interface NounDef {
     '@description': string;

package/dist/Types/Command.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Command.types.d.ts","sourceRoot":"","sources":["../../src/Types/Command.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,SAAS,MAAM,EAAE,CAAC;AAI5C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CAC1C;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,GAAG,KAAK,IAAI,YAAY,CAE1F;AAED,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;CACzD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,GAAG,WAAW,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEnD,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,IAAI,EAAE,WAAW,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"Command.types.d.ts","sourceRoot":"","sources":["../../src/Types/Command.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,yEAAyE;AACzE,MAAM,MAAM,cAAc,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,SAAS,MAAM,EAAE,CAAC;AAI5C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;CACzD;AAED,yDAAyD;AACzD,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,GAAG,KAAK,IAAI,YAAY,CAE1F;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,YAAY,GAClB,KAAK,IAAI,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC,CAE/E;AAED,yDAAyD;AACzD,MAAM,WAAW,OAAO;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,YAAY,CAAC,CAAC;CACzD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,GAAG,KAAK,GAAG,WAAW,CAAC;AAEzE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AAEnD,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,gFAAgF;IAChF,IAAI,EAAE,WAAW,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,cAAc,CAAC;IACxB,kEAAkE;IAClE,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/Types/Command.types.js

@@ -5,4 +5,8 @@
 export function isTypedVerbDef(entry) {
     return entry.typed === true;
 }
+/** Narrows to a hybrid TypedVerbDef that also carries a parent handler. */
+export function hasParentHandler(entry) {
+    return typeof entry.handler === 'function';
+}
 //# sourceMappingURL=Command.types.js.map

package/dist/Types/Command.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"Command.types.js","sourceRoot":"","sources":["../../src/Types/Command.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2BH,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,KAAoC;IACjE,OAAQ,KAAsB,CAAC,KAAK,KAAK,IAAI,CAAC;AAChD,CAAC"}
+{"version":3,"file":"Command.types.js","sourceRoot":"","sources":["../../src/Types/Command.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAoCH,yDAAyD;AACzD,MAAM,UAAU,cAAc,CAAC,KAAoC;IACjE,OAAQ,KAAsB,CAAC,KAAK,KAAK,IAAI,CAAC;AAChD,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAC9B,KAAmB;IAEnB,OAAO,OAAO,KAAK,CAAC,OAAO,KAAK,UAAU,CAAC;AAC7C,CAAC"}

package/dist/Utils/BuildPolling.d.ts

@@ -0,0 +1,18 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import type { MaafBuildPollResult } from '@microsoft/managed-apps-actions';
+export interface WaitForBuildStatusArgs {
+    appName: string;
+    commitSha: string;
+    initialWaitMs: number;
+    isJsonMode: boolean;
+    spinnerLabel?: string;
+}
+/**
+ * Polls `buildStatusAsync` for the given app + commit until the build reaches a
+ * terminal state. Shared between `ms app build` and `ms app play --mode preview`
+ * so both verbs surface identical waiting/error UX.
+ */
+export declare function waitForBuildStatusAsync(args: WaitForBuildStatusArgs): Promise<MaafBuildPollResult>;
+//# sourceMappingURL=BuildPolling.d.ts.map

package/dist/Utils/BuildPolling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildPolling.d.ts","sourceRoot":"","sources":["../../src/Utils/BuildPolling.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAS3E,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,mBAAmB,CAAC,CAiC9B"}

package/dist/Utils/BuildPolling.js

@@ -0,0 +1,63 @@
+/*!
+ * Copyright (C) Microsoft Corporation. All rights reserved.
+ */
+import { buildStatusAsync } from '@microsoft/managed-apps-actions';
+import { getCliLogger } from '../CliSettings.js';
+import { AppError } from '../Errors/CliError.js';
+import { CliSpinner } from './Spinner.js';
+const MIN_POLL_INTERVAL_MS = 1000;
+/**
+ * Polls `buildStatusAsync` for the given app + commit until the build reaches a
+ * terminal state. Shared between `ms app build` and `ms app play --mode preview`
+ * so both verbs surface identical waiting/error UX.
+ */
+export async function waitForBuildStatusAsync(args) {
+    const logger = getCliLogger();
+    let waitMs = Math.max(MIN_POLL_INTERVAL_MS, args.initialWaitMs);
+    const spinner = args.isJsonMode ? null : new CliSpinner();
+    spinner?.start(args.spinnerLabel ?? 'Waiting for build status...');
+    try {
+        for (;;) {
+            await sleep(waitMs);
+            const status = await buildStatusAsync({
+                logger,
+                actionsParams: { appName: args.appName, commitSha: args.commitSha },
+            });
+            switch (status.status) {
+                case 'Succeeded':
+                    return status;
+                case 'Failed':
+                case 'Canceled':
+                    throw new AppError(`Build ${status.status.toLowerCase()}${formatStatusDetail(status.result)}.`);
+                case 'NotStarted':
+                case 'Running':
+                    waitMs = Math.max(MIN_POLL_INTERVAL_MS, status.retryAfterMs ?? waitMs);
+                    break;
+                default:
+                    return status;
+            }
+        }
+    }
+    finally {
+        spinner?.stop();
+    }
+}
+function formatStatusDetail(result) {
+    if (typeof result === 'string' && result.trim()) {
+        return `: ${result}`;
+    }
+    if (result && typeof result === 'object') {
+        const parts = [];
+        if (typeof result.code === 'string' && result.code)
+            parts.push(result.code);
+        if (typeof result.message === 'string' && result.message)
+            parts.push(result.message);
+        if (parts.length > 0)
+            return `: ${parts.join(' - ')}`;
+    }
+    return '';
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=BuildPolling.js.map

package/dist/Utils/BuildPolling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildPolling.js","sourceRoot":"","sources":["../../src/Utils/BuildPolling.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AAEnE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAUlC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAA4B;IAE5B,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IAChE,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,EAAE,CAAC;IAE1D,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,YAAY,IAAI,6BAA6B,CAAC,CAAC;IACnE,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;YACpB,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;gBACpC,MAAM;gBACN,aAAa,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE;aACpE,CAAC,CAAC;YAEH,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;gBACtB,KAAK,WAAW;oBACd,OAAO,MAAM,CAAC;gBAChB,KAAK,QAAQ,CAAC;gBACd,KAAK,UAAU;oBACb,MAAM,IAAI,QAAQ,CAChB,SAAS,MAAM,CAAC,MAAM,CAAC,WAAW,EAAE,GAAG,kBAAkB,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAC5E,CAAC;gBACJ,KAAK,YAAY,CAAC;gBAClB,KAAK,SAAS;oBACZ,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,CAAC;oBACvE,MAAM;gBACR;oBACE,OAAO,MAAM,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,OAAO,EAAE,IAAI,EAAE,CAAC;IAClB,CAAC;AACH,CAAC;AAED,SAAS,kBAAkB,CAAC,MAAqC;IAC/D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QAChD,OAAO,KAAK,MAAM,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzC,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5E,IAAI,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACrF,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,KAAK,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;IACxD,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/Utils/BuildVerbDescriptionTable.d.ts

@@ -13,7 +13,17 @@ export declare function buildVerbDescriptionTable(): string;
 export declare function buildNounHelpText(noun: string): string;
 /**
  * Builds help text for a typed subcommand verb (e.g., `app add`).
- * Lists the available types.
+ * Lists the available types — including nested typed verbs.
  */
 export declare function buildTypedSubcommandHelpText(noun: string, verb: string): string;
+/**
+ * Walks the command tree along `pathTokens` and, if the endpoint is a typed
+ * verb, returns its flattened subcommand help text. Returns `null` if any
+ * token fails to match or the endpoint is a leaf (in which case Commander
+ * handles `--help` on its own at the leaf level).
+ *
+ * Used to surface help for nested-typed paths the resolver cannot leaf-match,
+ * e.g. `ms app share link --help` → list `create | list | revoke`.
+ */
+export declare function buildPathTypedHelpText(pathTokens: readonly string[]): string | null;
 //# sourceMappingURL=BuildVerbDescriptionTable.d.ts.map

package/dist/Utils/BuildVerbDescriptionTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BuildVerbDescriptionTable.d.ts","sourceRoot":"","sources":["../../src/Utils/BuildVerbDescriptionTable.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAkBlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4CtD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAmB/E"}
+{"version":3,"file":"BuildVerbDescriptionTable.d.ts","sourceRoot":"","sources":["../../src/Utils/BuildVerbDescriptionTable.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkBH;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAkBlD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4CtD;AAoBD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CA6BnF"}