@xano/cli 1.2.0 → 1.3.1-beta.0

package/dist/utils/flatten.js

@@ -0,0 +1,68 @@
+import snakeCase from 'lodash.snakecase';
+import * as fs from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { placeDocuments, splitMultidoc } from './document-parser.js';
+/**
+ * Split ONE multi-document `.xs` bundle (documents joined by `---`) into the
+ * standard per-document tree — the exact layout `pull` produces — using the
+ * shared `placeDocuments` placement so the two never drift.
+ *
+ * Filesystem-touching, but self-contained: it reads the bundle, resolves every
+ * document's destination, checks for collisions, writes, and (unless
+ * `keepSource`) removes the original. Throws on a destination collision when
+ * `force` is not set, and never deletes the source when a written document
+ * landed on the source's own path.
+ *
+ * Shared by the `flatten` command and the push-time prompt, so a user who
+ * confirms "flatten now?" gets byte-identical output to running `xano flatten`.
+ */
+export function flattenBundleFile(bundleFile, opts = {}) {
+    const { dryRun = false, force = false, keepSource = false, log } = opts;
+    const content = fs.readFileSync(bundleFile, 'utf8').trim();
+    const documents = splitMultidoc(content);
+    if (documents.length === 0)
+        return { removedSource: false, skipped: 'empty', written: [] };
+    if (documents.length === 1)
+        return { removedSource: false, skipped: 'single', written: [] };
+    const outputDir = opts.outputDir ? resolve(opts.outputDir) : dirname(bundleFile);
+    const placed = placeDocuments(documents, { join, relative, snakeCase });
+    // Pre-check destination collisions (unless --force / dry-run). A written file
+    // landing on the source's own path is not a clash — it replaces the bundle.
+    if (!dryRun && !force) {
+        const clashes = placed
+            .map((p) => join(outputDir, p.relPath))
+            .filter((abs) => fs.existsSync(abs) && resolve(abs) !== resolve(bundleFile));
+        if (clashes.length > 0) {
+            throw new Error(`Destination file(s) already exist (use --force to overwrite):\n` +
+                clashes.map((c) => `    ${relative(process.cwd(), c) || c}`).join('\n'));
+        }
+    }
+    const written = [];
+    for (const p of placed) {
+        const abs = join(outputDir, p.relPath);
+        if (log)
+            log(`  WRITE  ${relative(process.cwd(), abs) || p.relPath}`);
+        if (!dryRun) {
+            fs.mkdirSync(dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, p.content.endsWith('\n') ? p.content : `${p.content}\n`, 'utf8');
+        }
+        written.push(abs);
+    }
+    // Remove the original bundle unless asked to keep it, and never when a split
+    // document was written over the source's own path.
+    let removedSource = false;
+    if (!dryRun && !keepSource) {
+        const wroteOverSource = placed.some((p) => resolve(join(outputDir, p.relPath)) === resolve(bundleFile));
+        if (wroteOverSource) {
+            if (log)
+                log(`  (source ${basename(bundleFile)} was overwritten by a split document; not deleting)`);
+        }
+        else {
+            fs.rmSync(bundleFile);
+            removedSource = true;
+            if (log)
+                log(`  removed ${relative(process.cwd(), bundleFile) || bundleFile}`);
+        }
+    }
+    return { removedSource, written };
+}

package/dist/utils/knowledge-sync.d.ts

@@ -17,6 +17,7 @@ export interface KnowledgeObject {
     mode?: string;
     name: string;
     scope?: string;
+    tag?: string[];
 }
 /** A locally-collected object that also remembers its primary file on disk (for GUID writeback). */
 export interface LocalKnowledgeObject extends KnowledgeObject {

package/dist/utils/knowledge-sync.js

@@ -1,4 +1,3 @@
-/* eslint-disable camelcase -- knowledge_type / dry_run / guid_map are external Metadata API field names */
 import * as yaml from 'js-yaml';
 import snakeCase from 'lodash.snakecase';
 import { minimatch } from 'minimatch';
@@ -12,7 +11,7 @@ import { dirname, join, relative, sep } from 'node:path';
 // let the server dictate file paths.
 export const KNOWLEDGE_DIR = 'knowledge';
 // ── Frontmatter ──────────────────────────────────────────────────────────────
-const FRONTMATTER_ORDER = ['name', 'description', 'knowledge_type', 'scope', 'inclusion', 'enabled', 'guid'];
+const FRONTMATTER_ORDER = ['name', 'description', 'knowledge_type', 'inclusion', 'tags', 'guid'];
 /**
  * Build a primary `.md` file body: YAML frontmatter (built from the object's
  * structured fields) followed by the markdown content.
@@ -23,12 +22,10 @@ export function buildPrimaryContent(obj) {
     if (obj.description !== undefined)
         meta.description = obj.description;
     meta.knowledge_type = obj.knowledge_type;
-    if (obj.scope !== undefined)
-        meta.scope = obj.scope;
     if (obj.mode !== undefined)
         meta.inclusion = modeToInclusion(obj.mode);
-    if (obj.enabled !== undefined)
-        meta.enabled = obj.enabled;
+    if (obj.tag !== undefined && obj.tag.length > 0)
+        meta.tags = obj.tag;
     if (obj.guid !== undefined)
         meta.guid = obj.guid;
     // Emit keys in a stable, human-friendly order.
@@ -107,6 +104,10 @@ const MODE_TO_INCLUSION = {
 function modeToInclusion(mode) {
     return MODE_TO_INCLUSION[mode] ?? mode;
 }
+/** Parse the on-disk `tags:` frontmatter value into a string array, or `undefined` if absent/malformed. */
+function parseTags(tags) {
+    return Array.isArray(tags) && tags.every((t) => typeof t === 'string') ? tags : undefined;
+}
 // ── Path mapping (CLI-owned layout) ────────────────────────────────────────────
 /**
  * Allocate a unique snake_case folder/file segment per call, suffixing
@@ -246,6 +247,9 @@ export function collectKnowledgeObjects(inputDir, include, exclude) {
         };
         if (typeof meta.guid === 'string')
             obj.guid = meta.guid;
+        const tags = parseTags(meta.tags);
+        if (tags)
+            obj.tag = tags;
         if (knowledgeType === 'skill') {
             const skillFolder = posixPath.slice('skills/'.length, posixPath.indexOf('/SKILL.md'));
             const refPrefix = `skills/${skillFolder}/references/`;
@@ -345,6 +349,7 @@ function canonical(obj) {
         files,
         mode: obj.mode ?? '',
         scope: obj.scope ?? '',
+        tag: [...(obj.tag ?? [])].sort(),
     });
 }
 /**

package/dist/utils/microservice-wait.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Poll a tenant's microservice deployment status until every auto-deployed
+ * microservice settles (ok/error) or a timeout elapses. Backs `ephemeral push
+ * --wait`: after a multidoc push auto-deploys microservices (tenant_deploy=
+ * "auto"), the CLI waits here for them to become Ready and reports the outcome.
+ *
+ * The backend route (GET .../tenant/{name}/microservice, statement
+ * mvp:microservice_status_all) returns one entry per microservice with a live
+ * k8s readiness read. `manual`/`disabled` microservices are reported but not
+ * waited on (they were never deployed by the push).
+ */
+/** One microservice's status as returned by the tenant status route. */
+export interface MicroserviceStatusEntry {
+    desired?: number;
+    detail?: string;
+    microservice_id: number;
+    name: string;
+    ready?: number;
+    status: string;
+    tenant_deploy?: string;
+}
+export interface WaitOptions {
+    /** Bearer token for the authed status GET. */
+    accessToken: string;
+    /** Called once per poll with the latest entries, for progress rendering. */
+    onPoll?: (entries: MicroserviceStatusEntry[], elapsedMs: number) => void;
+    /** Poll cadence in ms (default 2000). */
+    pollIntervalMs?: number;
+    /** Absolute URL of the tenant microservice status route. */
+    statusUrl: string;
+    /** Overall wait budget in ms (default 300000 = 300s). */
+    timeoutMs?: number;
+    /** Verbose request logging passthrough. */
+    verbose?: boolean;
+    /** Authed fetch (command.verboseFetch bound), so TLS/dispatcher settings apply. */
+    verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
+}
+export interface WaitResult {
+    /** The final status entries observed. */
+    entries: MicroserviceStatusEntry[];
+    /** True if any awaited (auto) microservice ended in "error". */
+    hadError: boolean;
+    /** True if the wait budget elapsed before all awaited microservices settled. */
+    timedOut: boolean;
+}
+/** An awaited microservice is one that was auto-deployed and is not skipped/disabled. */
+export declare function isAwaited(entry: MicroserviceStatusEntry): boolean;
+/**
+ * Poll until all awaited microservices settle or the timeout elapses. Transient
+ * poll failures (network blips, a brief 5xx while a pod restarts) are tolerated —
+ * they don't abort the wait; only the overall timeout does.
+ */
+export declare function waitForMicroservices(opts: WaitOptions): Promise<WaitResult>;

package/dist/utils/microservice-wait.js

@@ -0,0 +1,84 @@
+/**
+ * Poll a tenant's microservice deployment status until every auto-deployed
+ * microservice settles (ok/error) or a timeout elapses. Backs `ephemeral push
+ * --wait`: after a multidoc push auto-deploys microservices (tenant_deploy=
+ * "auto"), the CLI waits here for them to become Ready and reports the outcome.
+ *
+ * The backend route (GET .../tenant/{name}/microservice, statement
+ * mvp:microservice_status_all) returns one entry per microservice with a live
+ * k8s readiness read. `manual`/`disabled` microservices are reported but not
+ * waited on (they were never deployed by the push).
+ */
+/** Statuses that mean an awaited microservice has settled (no longer in flight). */
+const SETTLED = new Set(['error', 'ok']);
+/** Statuses that mean we don't wait on this microservice at all. */
+const NOT_AWAITED = new Set(['disabled', 'skipped']);
+const sleep = (ms) => new Promise((r) => {
+    setTimeout(r, ms);
+});
+/** An awaited microservice is one that was auto-deployed and is not skipped/disabled. */
+export function isAwaited(entry) {
+    return !NOT_AWAITED.has(entry.status) && (entry.tenant_deploy ?? 'auto') !== 'manual';
+}
+/** True once every awaited microservice has settled (ok/error). */
+function allSettled(entries) {
+    const awaited = entries.filter((e) => isAwaited(e));
+    // No auto microservices at all → nothing to wait for.
+    if (awaited.length === 0)
+        return true;
+    return awaited.every((e) => SETTLED.has(e.status));
+}
+/**
+ * Fetch the status route once. Throws on a non-2xx so the caller can decide
+ * whether a transient failure is fatal (it isn't — we keep polling).
+ */
+async function fetchStatus(opts) {
+    const res = await opts.verboseFetch(opts.statusUrl, { headers: { Authorization: `Bearer ${opts.accessToken}` }, method: 'GET' }, opts.verbose ?? false, opts.accessToken);
+    if (!res.ok) {
+        throw new Error(`status ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.json());
+    if (!Array.isArray(body)) {
+        throw new TypeError('unexpected status response shape');
+    }
+    return body;
+}
+/**
+ * Poll until all awaited microservices settle or the timeout elapses. Transient
+ * poll failures (network blips, a brief 5xx while a pod restarts) are tolerated —
+ * they don't abort the wait; only the overall timeout does.
+ */
+export async function waitForMicroservices(opts) {
+    const pollIntervalMs = opts.pollIntervalMs ?? 2000;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    const start = Date.now();
+    let entries = [];
+    // Poll loop. We always do at least one fetch so `--wait` reports even when the
+    // deployment already settled between the push returning and the first poll.
+    for (;;) {
+        const elapsed = Date.now() - start;
+        try {
+            // eslint-disable-next-line no-await-in-loop -- polling is sequential by design
+            entries = await fetchStatus(opts);
+            opts.onPoll?.(entries, elapsed);
+            if (allSettled(entries)) {
+                return { entries, hadError: entries.some((e) => isAwaited(e) && e.status === 'error'), timedOut: false };
+            }
+        }
+        catch {
+            // A transient status read failure is non-fatal — keep polling until the
+            // overall timeout. There is deliberately no consecutive-failure cap: we
+            // don't surface each blip, and the timeout is the only failure signal.
+        }
+        if (Date.now() - start + pollIntervalMs > timeoutMs) {
+            // Out of budget. Report whatever we last saw as timed out.
+            return {
+                entries,
+                hadError: entries.some((e) => isAwaited(e) && e.status === 'error'),
+                timedOut: true,
+            };
+        }
+        // eslint-disable-next-line no-await-in-loop -- pacing the poll loop is the point
+        await sleep(pollIntervalMs);
+    }
+}

package/dist/utils/multidoc-push.d.ts

@@ -1,4 +1,4 @@
-import { Command } from '@oclif/core';
+import { Command, Errors } from '@oclif/core';
 import { type BadIndex, type BadReference } from './reference-checker.js';
 export interface PushFlags {
     delete: boolean;
@@ -21,6 +21,11 @@ export interface PushTarget {
     buildPushUrl: (queryParams: URLSearchParams) => string;
     /** CLI version string */
     cliVersion: string;
+    /**
+     * Guidance for a refusal this target recognises, given the HTTP status and the server's payload.
+     * A preview or import refused that way stops with the message and this guidance appended.
+     */
+    explainRefusal?: (status: number, payload: unknown) => string | undefined;
     /** Instance origin URL (e.g., "https://x123-abcd-1234.xano.io") */
     instanceOrigin: string;
     /** Human-readable label for log messages (e.g., "sandbox environment", "workspace 40") */
@@ -54,8 +59,56 @@ export interface PushContext {
     inputDir: string;
     /** Optional knowledge sync config. Only workspace push sets this. */
     knowledge?: KnowledgeConfig;
+    /** Where progress and diagnostics go; defaults to the command's stdout. */
+    log?: (message: string) => void;
     verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
 }
+export interface DryRunSummary {
+    created: number;
+    deleted: number;
+    truncated: number;
+    unchanged: number;
+    updated: number;
+}
+export interface DryRunOperation {
+    action: string;
+    details: string;
+    name: string;
+    reason?: string;
+    type: string;
+}
+export interface DryRunResult {
+    operations: DryRunOperation[];
+    /** True when the sandbox currently holds a different source workspace than the one being pushed. */
+    source_workspace_mismatch?: boolean;
+    summary: Record<string, DryRunSummary>;
+    workspace_name?: string;
+}
+/** What a push did, for the calling command to report. */
+export interface PushResult {
+    knowledge: {
+        deleted: number;
+        imported: number;
+    };
+    preview: DryRunResult | null;
+    /** The multidoc import's response body; absent when no multidoc was imported. */
+    response?: Record<string, unknown>;
+    /** The documents the multidoc import carried. */
+    sent: Array<{
+        content: string;
+        filePath: string;
+    }>;
+    /** Why the push stopped before writing anything, when it did. */
+    stopped?: 'blocked' | 'cancelled' | 'dry-run' | 'no-changes';
+}
+/**
+ * A push that failed after its multidoc import landed. The import is not rolled back, so the error
+ * carries what it did for the calling command to report beside the failure.
+ */
+export declare class FailedAfterImportError extends Errors.CLIError {
+    readonly imported: PushResult;
+    constructor(message: string, imported: PushResult);
+}
 /**
  * Filter document entries down to the ones the dry-run preview reports as changed,
  * used to send only the changed documents during a partial (non-`--sync`) push.
@@ -89,7 +142,61 @@ export declare function collectFiles(dir: string): string[];
  * Apply include/exclude glob filters to a file list. Logs filter results.
  * Returns the filtered file list.
  */
+/**
+ * Normalize a filter pattern into one minimatch can actually match against a
+ * repo-relative FILE path.
+ *
+ * minimatch has no notion of "this pattern names a directory", and the two
+ * spellings a person reaches for first both silently match NOTHING:
+ *
+ *   "table/"  a trailing slash is not directory syntax; it matches nothing
+ *   "table"   no slash, so `matchBase` compares it to the file's BASENAME,
+ *             i.e. it asks "is this file called `table`", not "is it under
+ *             `table/`"
+ *
+ * Silently matching nothing is the dangerous half of this: combined with
+ * `--delete`, a filter that fails open pushes more than intended, and a filter
+ * that succeeds deletes what it was meant to protect. So a pattern that names a
+ * real directory is expanded to `<dir>/**` rather than left to match nothing.
+ */
+export declare function normalizeFilterPattern(pattern: string, inputDir: string): string;
 export declare function applyFilters(files: string[], inputDir: string, include: string[] | undefined, exclude: string[] | undefined, log: (msg: string) => void): string[];
+/** A document the filter removed from the push, and therefore must protect. */
+export interface FilteredOutDocument {
+    guid?: string;
+    key: string;
+    name: string;
+    relPath: string;
+    type: string;
+}
+/**
+ * Describe the documents a --include/--exclude filter removed.
+ *
+ * These are the objects the user asked NOT to touch, and they are exactly the
+ * ones a `--delete` sweep would remove: a filtered-out document never reaches
+ * the payload, so the server reads it as deleted from the tree. Their GUIDs are
+ * sent as `protect_guids` so the server spares them, and their keys are used to
+ * VERIFY the server actually did.
+ */
+export declare function describeFilteredOut(allFiles: string[], keptFiles: string[], inputDir: string): FilteredOutDocument[];
+/**
+ * Delete operations that would remove something the filter excluded.
+ *
+ * This is the guard's actual test, and it is deliberately performed against the
+ * dry-run the SERVER returned rather than trusting that `protect_guids` was
+ * honoured: an older instance ignores the parameter entirely, and a document
+ * with no GUID cannot be protected at all. Either way the answer here is the
+ * truth about what the push is about to do.
+ */
+export declare function deletesHittingFilteredOut(operations: Array<{
+    action: string;
+    name: string;
+    type: string;
+}>, filteredOut: FilteredOutDocument[]): Array<{
+    name: string;
+    relPath: string;
+    type: string;
+}>;
 /**
  * Read .xs files into document entries, skipping empty files.
  */
@@ -97,6 +204,40 @@ export declare function readDocuments(files: string[]): Array<{
     content: string;
     filePath: string;
 }>;
+/**
+ * Return the entries whose file holds more than one document (a `---`
+ * separator). Used to refuse multi-doc files before the push pipeline's
+ * single-doc-per-file assumptions can drop or corrupt them.
+ */
+export declare function findMultiDocEntries(entries: Array<{
+    content: string;
+    filePath: string;
+}>): Array<{
+    count: number;
+    filePath: string;
+}>;
+/**
+ * Return every `workspace` document in the push set, with the name it declares.
+ *
+ * A tree must carry at most ONE. The server applies the first workspace
+ * document it encounters to the workspace being pushed into and silently
+ * discards the rest, with no check that the document actually describes that
+ * workspace — so a second one renames the destination to a foreign name while
+ * leaving its content untouched, and which name wins flips with the contents of
+ * the pushed set.
+ *
+ * Trees accumulate a second one easily, because `pull` names the file after the
+ * workspace's own name (`workspace/{name}.xs`): pulling a different workspace
+ * into the same directory ADDS a file rather than overwriting, and renaming a
+ * workspace leaves the old-name file behind.
+ */
+export declare function findWorkspaceEntries(entries: Array<{
+    content: string;
+    filePath: string;
+}>): Array<{
+    filePath: string;
+    name: string;
+}>;
 export declare function renderBadReferences(badRefs: BadReference[], log: (msg: string) => void): void;
 export declare function renderBadIndexes(badIndexes: BadIndex[], log: (msg: string) => void): void;
 export declare function confirm(message: string): Promise<boolean>;
@@ -104,7 +245,7 @@ export declare function confirm(message: string): Promise<boolean>;
  * Execute a multidoc push with preview, validation, partial mode, and GUID sync.
  * Shared by both sandbox:push and workspace:push commands.
  */
-export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<void>;
+export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<PushResult>;
 /**
  * Turn a thrown fetch/network error into an actionable message.
  *