sb-mig 6.1.1 → 6.2.0

package/dist/api/inspect/component-usage-query.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentUsageQuery } from "./component-usage.types.js";
+export declare const discoverComponentUsageQueryFiles: (queryName: string) => string[];
+export declare const loadComponentUsageQueryFromPath: (queryPath: string) => Promise<ComponentUsageQuery>;
+export declare const loadComponentUsageQuery: (queryNameOrPath: string) => Promise<ComponentUsageQuery>;

package/dist/api/inspect/component-usage-query.js

@@ -0,0 +1,72 @@
+import path from "path";
+import storyblokConfig from "../../config/config.js";
+import { toImportSpecifier } from "../../utils/files.js";
+import { safeGlobSync as globSync } from "../../utils/glob-utils.js";
+import { normalizeDiscover } from "../../utils/path-utils.js";
+const QUERY_EXTENSIONS = [
+    "sb.query.js",
+    "sb.query.cjs",
+    "sb.query.mjs",
+];
+const isDirectQueryPath = (queryNameOrPath) => queryNameOrPath.includes("/") ||
+    queryNameOrPath.includes("\\") ||
+    QUERY_EXTENSIONS.some((ext) => queryNameOrPath.endsWith(`.${ext}`));
+const withoutKnownQueryExtension = (queryName) => {
+    for (const ext of QUERY_EXTENSIONS) {
+        const suffix = `.${ext}`;
+        if (queryName.endsWith(suffix)) {
+            return queryName.slice(0, -suffix.length);
+        }
+    }
+    return queryName;
+};
+const querySearchDirectories = () => storyblokConfig.componentsDirectories.filter((directory) => !directory.includes("node_modules"));
+export const discoverComponentUsageQueryFiles = (queryName) => {
+    const rootDirectory = path.resolve(process.cwd(), "./");
+    const searchDirectories = querySearchDirectories();
+    const normalizedQueryName = withoutKnownQueryExtension(queryName);
+    return QUERY_EXTENSIONS.flatMap((ext) => {
+        const pattern = path.join(rootDirectory, normalizeDiscover({ segments: searchDirectories }), "**", `${normalizedQueryName}.${ext}`);
+        return globSync(pattern.replace(/\\/g, "/"), {
+            follow: true,
+        });
+    });
+};
+function assertValidQuery(query, sourcePath) {
+    if (!query || typeof query !== "object") {
+        throw new Error(`Query file '${sourcePath}' must export an object.`);
+    }
+    const candidate = query;
+    if (typeof candidate.name !== "string" || candidate.name.length === 0) {
+        throw new Error(`Query file '${sourcePath}' must export a non-empty 'name'.`);
+    }
+    if (typeof candidate.match !== "function") {
+        throw new Error(`Query file '${sourcePath}' must export a 'match' function.`);
+    }
+}
+export const loadComponentUsageQueryFromPath = async (queryPath) => {
+    const resolvedPath = path.isAbsolute(queryPath)
+        ? queryPath
+        : path.resolve(process.cwd(), queryPath);
+    const module = await import(
+    /* @vite-ignore */ toImportSpecifier(resolvedPath));
+    const query = module.default || module;
+    assertValidQuery(query, resolvedPath);
+    return query;
+};
+export const loadComponentUsageQuery = async (queryNameOrPath) => {
+    if (!queryNameOrPath || queryNameOrPath.trim().length === 0) {
+        throw new Error("--query is required for inspect component-usage.");
+    }
+    if (isDirectQueryPath(queryNameOrPath)) {
+        return loadComponentUsageQueryFromPath(queryNameOrPath);
+    }
+    const discoveredFiles = discoverComponentUsageQueryFiles(queryNameOrPath);
+    if (discoveredFiles.length === 0) {
+        throw new Error(`No component usage query found for '${queryNameOrPath}'. Expected a file named '${queryNameOrPath}.sb.query.js', '${queryNameOrPath}.sb.query.cjs', or '${queryNameOrPath}.sb.query.mjs' in configured component directories.`);
+    }
+    if (discoveredFiles.length > 1) {
+        throw new Error(`Multiple component usage queries found for '${queryNameOrPath}': ${discoveredFiles.join(", ")}`);
+    }
+    return loadComponentUsageQueryFromPath(discoveredFiles[0]);
+};

package/dist/api/inspect/component-usage.d.ts

@@ -0,0 +1,8 @@
+import type { ComponentUsageMatch, ComponentUsageQuery, ComponentUsageReport, ComponentUsageStoryRef, InspectFetchedStoriesArgs, InspectStoryblokStoriesArgs } from "./component-usage.types.js";
+import type { RequestBaseConfig } from "../utils/request.js";
+export declare const inspectStoryContent: ({ story, query, }: {
+    story: ComponentUsageStoryRef;
+    query: ComponentUsageQuery;
+}) => Promise<ComponentUsageMatch[]>;
+export declare const inspectFetchedStories: ({ stories, query, spaceId, filters, }: InspectFetchedStoriesArgs) => Promise<ComponentUsageReport>;
+export declare const inspectStoryblokStories: (args: InspectStoryblokStoriesArgs, config: RequestBaseConfig) => Promise<ComponentUsageReport>;

package/dist/api/inspect/component-usage.js

@@ -0,0 +1,159 @@
+import { getAllStories, getStoryBySlug } from "../stories/stories.js";
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+const isComponentNode = (value) => isRecord(value) && typeof value.component === "string";
+const normalizeStory = (storyData) => {
+    const story = storyData?.story || storyData || {};
+    return story;
+};
+const storyHasContent = (story) => isRecord(story.content);
+const normalizeMatchDetails = (matchResult) => {
+    if (matchResult === true) {
+        return undefined;
+    }
+    if (isRecord(matchResult)) {
+        return matchResult;
+    }
+    return undefined;
+};
+const createMatch = ({ node, context, matchResult, }) => {
+    const details = normalizeMatchDetails(matchResult);
+    const match = {
+        storyId: context.story.id,
+        storyName: context.story.name,
+        storySlug: context.story.slug,
+        storyFullSlug: context.story.full_slug,
+        component: node.component,
+        uid: typeof node._uid === "string" ? node._uid : undefined,
+        path: context.path,
+        parentComponent: typeof context.parent?.component === "string"
+            ? context.parent.component
+            : undefined,
+        parentUid: typeof context.parent?._uid === "string"
+            ? context.parent._uid
+            : undefined,
+    };
+    if (details) {
+        match.details = details;
+    }
+    return match;
+};
+const joinPath = (path, segment) => path.length > 0 ? `${path}.${segment}` : segment;
+const walkValue = async ({ value, path, story, parent, ancestors, query, matches, }) => {
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            await walkValue({
+                value: value[i],
+                path: `${path}[${i}]`,
+                story,
+                parent,
+                ancestors,
+                query,
+                matches,
+            });
+        }
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    const currentParent = isComponentNode(value) ? value : parent;
+    const currentAncestors = isComponentNode(value)
+        ? [...ancestors, value]
+        : ancestors;
+    if (isComponentNode(value)) {
+        const context = {
+            story,
+            path,
+            parent,
+            ancestors,
+        };
+        const matchResult = await query.match(value, context);
+        if (matchResult) {
+            matches.push(createMatch({
+                node: value,
+                context,
+                matchResult,
+            }));
+        }
+    }
+    for (const [key, child] of Object.entries(value)) {
+        if (key === "_uid" || key === "component") {
+            continue;
+        }
+        await walkValue({
+            value: child,
+            path: joinPath(path, key),
+            story,
+            parent: currentParent,
+            ancestors: currentAncestors,
+            query,
+            matches,
+        });
+    }
+};
+export const inspectStoryContent = async ({ story, query, }) => {
+    const matches = [];
+    if (!storyHasContent(story)) {
+        return matches;
+    }
+    await walkValue({
+        value: story.content,
+        path: "content",
+        story,
+        query,
+        matches,
+        ancestors: [],
+    });
+    return matches;
+};
+export const inspectFetchedStories = async ({ stories, query, spaceId, filters = {}, }) => {
+    const selectedStories = stories
+        .map(normalizeStory)
+        .filter((story) => !story.is_folder);
+    const matchesByStory = await Promise.all(selectedStories.map(async (story) => inspectStoryContent({ story, query })));
+    const matches = matchesByStory.flat();
+    const matchedStoryIds = new Set(matches.map((match) => match.storyId));
+    return {
+        queryName: query.name,
+        spaceId,
+        generatedAt: new Date().toISOString(),
+        filters,
+        totals: {
+            storiesScanned: selectedStories.length,
+            storiesMatched: matchedStoryIds.size,
+            matches: matches.length,
+        },
+        matches,
+    };
+};
+const resolveStoryFetchOptions = (filters) => {
+    if (filters.startsWith) {
+        return { starts_with: filters.startsWith };
+    }
+    return {};
+};
+export const inspectStoryblokStories = async (args, config) => {
+    const { query, spaceId, filters } = args;
+    if (filters.withSlug && filters.withSlug.length > 0) {
+        const stories = await Promise.all(filters.withSlug.map((slug) => getStoryBySlug(slug, {
+            ...config,
+            spaceId,
+        })));
+        return inspectFetchedStories({
+            stories: stories.filter(Boolean),
+            query,
+            spaceId,
+            filters,
+        });
+    }
+    const stories = await getAllStories({ options: resolveStoryFetchOptions(filters) }, {
+        ...config,
+        spaceId,
+    });
+    return inspectFetchedStories({
+        stories,
+        query,
+        spaceId,
+        filters,
+    });
+};

package/dist/api/inspect/component-usage.types.d.ts

@@ -0,0 +1,61 @@
+export interface ComponentUsageStoryRef {
+    id: number | string;
+    name?: string;
+    slug?: string;
+    full_slug?: string;
+    is_folder?: boolean;
+    content?: Record<string, unknown>;
+}
+export interface ComponentUsageQueryContext {
+    story: ComponentUsageStoryRef;
+    path: string;
+    parent?: Record<string, unknown>;
+    ancestors: Array<Record<string, unknown>>;
+}
+export type ComponentUsageQueryMatchResult = boolean | Record<string, unknown> | null | undefined;
+export interface ComponentUsageQuery {
+    name: string;
+    description?: string;
+    match: (node: Record<string, any>, context: ComponentUsageQueryContext) => ComponentUsageQueryMatchResult | Promise<ComponentUsageQueryMatchResult>;
+}
+export interface ComponentUsageMatch {
+    storyId: number | string;
+    storyName?: string;
+    storySlug?: string;
+    storyFullSlug?: string;
+    component: string;
+    uid?: string;
+    path: string;
+    parentComponent?: string;
+    parentUid?: string;
+    details?: Record<string, unknown>;
+}
+export interface ComponentUsageFilters {
+    all?: boolean;
+    withSlug?: string[];
+    startsWith?: string;
+}
+export interface ComponentUsageReport {
+    queryName: string;
+    spaceId: string;
+    generatedAt: string;
+    filters: ComponentUsageFilters;
+    totals: {
+        storiesScanned: number;
+        storiesMatched: number;
+        matches: number;
+    };
+    matches: ComponentUsageMatch[];
+}
+export interface InspectFetchedStoriesArgs {
+    stories: any[];
+    query: ComponentUsageQuery;
+    spaceId: string;
+    filters?: ComponentUsageFilters;
+}
+export interface InspectStoryblokStoriesArgs {
+    query: ComponentUsageQuery;
+    spaceId: string;
+    filters: ComponentUsageFilters;
+    includeFolders?: boolean;
+}

package/dist/api/inspect/component-usage.types.js

@@ -0,0 +1 @@
+export {};

package/dist/api/inspect/index.d.ts

@@ -0,0 +1,3 @@
+export { inspectFetchedStories, inspectStoryblokStories, inspectStoryContent, } from "./component-usage.js";
+export { discoverComponentUsageQueryFiles, loadComponentUsageQuery, loadComponentUsageQueryFromPath, } from "./component-usage-query.js";
+export type { ComponentUsageFilters, ComponentUsageMatch, ComponentUsageQuery, ComponentUsageQueryContext, ComponentUsageReport, ComponentUsageStoryRef, } from "./component-usage.types.js";

package/dist/api/inspect/index.js

@@ -0,0 +1,2 @@
+export { inspectFetchedStories, inspectStoryblokStories, inspectStoryContent, } from "./component-usage.js";
+export { discoverComponentUsageQueryFiles, loadComponentUsageQuery, loadComponentUsageQueryFromPath, } from "./component-usage-query.js";

package/dist/api/managementApi.d.ts

@@ -1,3 +1,4 @@
+import * as inspect from "./inspect/index.js";
 import * as stories from "./stories/index.js";
 export declare const managementApi: {
     assets: {
@@ -31,6 +32,17 @@ export declare const managementApi: {
         updateDatasource: import("./datasources/datasources.types.js").UpdateDatasource;
         syncDatasources: import("./datasources/datasources.types.js").SyncDatasources;
     };
+    inspect: {
+        inspectFetchedStories: ({ stories, query, spaceId, filters, }: import("./inspect/component-usage.types.js").InspectFetchedStoriesArgs) => Promise<inspect.ComponentUsageReport>;
+        inspectStoryblokStories: (args: import("./inspect/component-usage.types.js").InspectStoryblokStoriesArgs, config: import("./utils/request.js").RequestBaseConfig) => Promise<inspect.ComponentUsageReport>;
+        inspectStoryContent: ({ story, query, }: {
+            story: inspect.ComponentUsageStoryRef;
+            query: inspect.ComponentUsageQuery;
+        }) => Promise<inspect.ComponentUsageMatch[]>;
+        discoverComponentUsageQueryFiles: (queryName: string) => string[];
+        loadComponentUsageQuery: (queryNameOrPath: string) => Promise<inspect.ComponentUsageQuery>;
+        loadComponentUsageQueryFromPath: (queryPath: string) => Promise<inspect.ComponentUsageQuery>;
+    };
     plugins: {
         getAllPlugins: import("./plugins/plugins.types.js").GetAllPlugins;
         getPlugin: import("./plugins/plugins.types.js").GetPlugin;

package/dist/api/managementApi.js

@@ -2,6 +2,7 @@ import * as assets from "./assets/index.js";
 import * as auth from "./auth/index.js";
 import * as components from "./components/index.js";
 import * as datasources from "./datasources/index.js";
+import * as inspect from "./inspect/index.js";
 import * as plugins from "./plugins/index.js";
 import * as presets from "./presets/index.js";
 import * as roles from "./roles/index.js";
@@ -12,6 +13,7 @@ export const managementApi = {
     auth: { ...auth },
     components: { ...components },
     datasources: { ...datasources },
+    inspect: { ...inspect },
     plugins: { ...plugins },
     presets: { ...presets },
     roles: { ...roles },

package/dist/cli/cli-descriptions.d.ts

@@ -1,4 +1,5 @@
-export declare const mainDescription = "\n    USAGE\n      $ sb-mig [command]\n\n    COMMANDS\n        sync                    Synchronize components, roles, datasources, plugins, stories, and assets.\n        copy                    Copy Storyblok stories or folders between spaces.\n        discover                Discover local components and migration config files.\n        backup                  Back up Storyblok resources to local JSON files.\n        migrate                 Run story or preset data migrations.\n        language-publish-state  Build a read-only story language publish-state map.\n        story-versions          Inspect raw Management API story version history for one story.\n        published-layer-export  Export draft/current and published story layers as JSON.\n        remove                  Remove components or stories from a Storyblok space.\n        revert                  Restore stories from a local story backup file.\n        migrations              Recognize migration commands to run for a package upgrade.\n        init                    Initialize project Storyblok environment settings.\n        debug                   Output extra debugging information.\n        help                    Show this screen.\n\n    EXAMPLES\n      $ sb-mig sync components --all\n      $ sb-mig migrate content --all --from 12345 --to 12345 --migration file-with-migration --dry-run\n      $ sb-mig copy stories --sourceSpace 12345 --targetSpace 67890 --what folder/* --where target-folder\n";
+export declare const mainDescription = "\n    USAGE\n      $ sb-mig [command]\n\n    COMMANDS\n        sync                    Synchronize components, roles, datasources, plugins, stories, and assets.\n        copy                    Copy Storyblok stories or folders between spaces.\n        inspect                 Inspect Storyblok content without writing changes.\n        discover                Discover local components and migration config files.\n        backup                  Back up Storyblok resources to local JSON files.\n        migrate                 Run story or preset data migrations.\n        language-publish-state  Build a read-only story language publish-state map.\n        story-versions          Inspect raw Management API story version history for one story.\n        published-layer-export  Export draft/current and published story layers as JSON.\n        remove                  Remove components or stories from a Storyblok space.\n        revert                  Restore stories from a local story backup file.\n        migrations              Recognize migration commands to run for a package upgrade.\n        init                    Initialize project Storyblok environment settings.\n        debug                   Output extra debugging information.\n        help                    Show this screen.\n\n    EXAMPLES\n      $ sb-mig sync components --all\n      $ sb-mig migrate content --all --from 12345 --to 12345 --migration file-with-migration --dry-run\n      $ sb-mig inspect component-usage --from 12345 --all --query flex-group-width-child\n      $ sb-mig copy stories --sourceSpace 12345 --targetSpace 67890 --what folder/* --where target-folder\n";
+export declare const inspectDescription = "\n    USAGE\n        $ sb-mig inspect component-usage --from [spaceId] --all --query [query-name]\n        $ sb-mig inspect component-usage --from [spaceId] --withSlug [full_slug] --query [query-name]\n        $ sb-mig inspect component-usage --from [spaceId] --startsWith [prefix] --query [query-name]\n\n    DESCRIPTION\n        Inspect Storyblok story content with a local component usage query file.\n        This command is read-only against Storyblok and writes a local JSON file only when --outputPath is passed.\n\n    COMMANDS\n        component-usage  Find component usage patterns in selected stories.\n\n    FLAGS\n        --from        Source space ID to inspect. Falls back to configured spaceId.\n        --all         Inspect all non-folder stories.\n        --withSlug    Exact story full_slug to inspect. Can be repeated.\n        --startsWith  Filter stories by starts_with prefix.\n        --query       Query file name or path. Looks for *.sb.query.js, *.sb.query.cjs, or *.sb.query.mjs.\n        --outputPath  Optional file path for JSON report output.\n\n    SIDE EFFECTS\n        Read-only against Storyblok. Writes a local JSON report only when --outputPath is passed.\n\n    GOTCHAS\n        Pass exactly one selection mode: --all, --withSlug, or --startsWith.\n        A query file must default-export an object with name and match(node, context).\n        TypeScript query files are planned, but the first implementation supports JS/CJS/MJS query files.\n\n    EXAMPLES\n        $ sb-mig inspect component-usage --from 12345 --all --query flex-group-width-child\n        $ sb-mig inspect component-usage --from 12345 --startsWith landing-pages --query ./queries/flex-group-width-child.sb.query.js --outputPath sbmig/usage/flex-group-width-child.json\n";
 export declare const storyVersionsDescription = "\n    USAGE\n        $ sb-mig story-versions --from [spaceId] --storyId [storyId]\n        $ sb-mig story-versions --from [spaceId] --withSlug [full_slug]\n\n    DESCRIPTION\n        Read Storyblok Management API story_versions for a single story.\n        This command is read-only and is meant for inspecting version status values and content shape.\n\n    FLAGS\n        --from            Source space ID to inspect. Required.\n        --storyId         Story ID to inspect. Required unless --withSlug is passed.\n        --withSlug        Story full_slug to resolve to a story ID. Required unless --storyId is passed.\n        --showContent     Include version content from Storyblok. Default: true.\n        --page            Versions page. Default: 1.\n        --perPage         Versions per page. Default: 25.\n        --raw             Print the raw Storyblok API response instead of the compact summary.\n        --outputPath      Optional file path for JSON output.\n\n    SIDE EFFECTS\n        Read-only against Storyblok. Writes a local JSON file only when --outputPath is passed.\n\n    EXAMPLES\n        $ sb-mig story-versions --from 12345 --storyId 98765\n        $ sb-mig story-versions --from 12345 --withSlug tours/europe --raw --outputPath sbmig/story-versions/tours-europe.raw.json\n";
 export declare const publishedLayerExportDescription = "\n    USAGE\n        $ sb-mig published-layer-export --from [spaceId] --all\n        $ sb-mig published-layer-export --from [spaceId] --storyId [storyId]\n        $ sb-mig published-layer-export --from [spaceId] --withSlug [full_slug]\n        $ sb-mig published-layer-export --from [spaceId] --startsWith [prefix]\n\n    DESCRIPTION\n        Read selected Management API stories and their latest published Story Versions API content.\n        This command is read-only against Storyblok. It writes JSON files for inspecting draft/current and published layers before changing migrate behavior.\n\n    FLAGS\n        --from            Source space ID to inspect. Required.\n        --all             Export all non-folder stories.\n        --storyId         Story ID to export. Can be repeated.\n        --withSlug        Exact story full_slug to export. Can be repeated.\n        --startsWith      Filter stories by starts_with prefix.\n        --fileName        Stable output base name.\n        --outputPath      Output directory. Default: sbmig/published-layer-export.\n        --versionsPerPage Story versions per page. Default: 25.\n        --maxVersionPages Maximum Story Versions API pages to inspect per story. Default: 4.\n\n    OUTPUT\n        <name>---draft-current-full.json\n        <name>---published-layer-full.json\n        <name>---dual-layer-summary.json\n\n    SIDE EFFECTS\n        Read-only against Storyblok. Always writes local JSON export files.\n\n    EXAMPLES\n        $ sb-mig published-layer-export --from 12345 --withSlug translation-migration-testing/test-1/contact-us\n        $ sb-mig published-layer-export --from 12345 --storyId 178888427520390\n        $ sb-mig published-layer-export --from 12345 --startsWith translation-migration-testing --fileName translation-test\n";
 export declare const languagePublishStateDescription = "\n    USAGE\n        $ sb-mig language-publish-state --from [spaceId]\n\n    DESCRIPTION\n        Read stories from a source Storyblok space and write a JSON map of default and translated language publication states.\n        This command is read-only against Storyblok. It uses Management API for story listing and default-language state, and Delivery API for translated language published/draft comparisons.\n\n    FLAGS\n        --from            Source space ID to inspect. Required.\n        --accessToken     Optional source space Delivery API access token override. Falls back to configured accessToken.\n        --languages       Languages to inspect: all, default,fr,de. Default: all.\n        --withSlug        Exact story full_slug to inspect. Can be repeated.\n        --startsWith      Filter stories by starts_with prefix.\n        --fileName        Stable output base name under sbmig/language-publish-state.\n        --outputPath      Explicit output path for the generated JSON file.\n\n    SIDE EFFECTS\n        Read-only against Storyblok. Writes a local JSON publish-state map.\n\n    EXAMPLES\n        $ sb-mig language-publish-state --from 12345 --startsWith about-ef --languages all --fileName about-ef-prod\n        $ sb-mig language-publish-state --from 12345 --accessToken xxx --withSlug about-ef/testimonials --languages default,fr\n";

package/dist/cli/cli-descriptions.js

@@ -5,6 +5,7 @@ export const mainDescription = `
     COMMANDS
         sync                    Synchronize components, roles, datasources, plugins, stories, and assets.
         copy                    Copy Storyblok stories or folders between spaces.
+        inspect                 Inspect Storyblok content without writing changes.
         discover                Discover local components and migration config files.
         backup                  Back up Storyblok resources to local JSON files.
         migrate                 Run story or preset data migrations.
@@ -21,8 +22,42 @@ export const mainDescription = `
     EXAMPLES
       $ sb-mig sync components --all
       $ sb-mig migrate content --all --from 12345 --to 12345 --migration file-with-migration --dry-run
+      $ sb-mig inspect component-usage --from 12345 --all --query flex-group-width-child
       $ sb-mig copy stories --sourceSpace 12345 --targetSpace 67890 --what folder/* --where target-folder
 `;
+export const inspectDescription = `
+    USAGE
+        $ sb-mig inspect component-usage --from [spaceId] --all --query [query-name]
+        $ sb-mig inspect component-usage --from [spaceId] --withSlug [full_slug] --query [query-name]
+        $ sb-mig inspect component-usage --from [spaceId] --startsWith [prefix] --query [query-name]
+
+    DESCRIPTION
+        Inspect Storyblok story content with a local component usage query file.
+        This command is read-only against Storyblok and writes a local JSON file only when --outputPath is passed.
+
+    COMMANDS
+        component-usage  Find component usage patterns in selected stories.
+
+    FLAGS
+        --from        Source space ID to inspect. Falls back to configured spaceId.
+        --all         Inspect all non-folder stories.
+        --withSlug    Exact story full_slug to inspect. Can be repeated.
+        --startsWith  Filter stories by starts_with prefix.
+        --query       Query file name or path. Looks for *.sb.query.js, *.sb.query.cjs, or *.sb.query.mjs.
+        --outputPath  Optional file path for JSON report output.
+
+    SIDE EFFECTS
+        Read-only against Storyblok. Writes a local JSON report only when --outputPath is passed.
+
+    GOTCHAS
+        Pass exactly one selection mode: --all, --withSlug, or --startsWith.
+        A query file must default-export an object with name and match(node, context).
+        TypeScript query files are planned, but the first implementation supports JS/CJS/MJS query files.
+
+    EXAMPLES
+        $ sb-mig inspect component-usage --from 12345 --all --query flex-group-width-child
+        $ sb-mig inspect component-usage --from 12345 --startsWith landing-pages --query ./queries/flex-group-width-child.sb.query.js --outputPath sbmig/usage/flex-group-width-child.json
+`;
 export const storyVersionsDescription = `
     USAGE
         $ sb-mig story-versions --from [spaceId] --storyId [storyId]

package/dist/cli/commands/inspect.d.ts

@@ -0,0 +1,2 @@
+import type { CLIOptions } from "../../utils/interfaces.js";
+export declare const inspect: (props: CLIOptions) => Promise<void>;

package/dist/cli/commands/inspect.js

@@ -0,0 +1,91 @@
+import { loadComponentUsageQuery } from "../../api/inspect/component-usage-query.js";
+import { inspectStoryblokStories } from "../../api/inspect/component-usage.js";
+import { createAndSaveToFile } from "../../utils/files.js";
+import Logger from "../../utils/logger.js";
+import { apiConfig } from "../api-config.js";
+import { getFrom } from "../utils/cli-utils.js";
+const INSPECT_COMMANDS = {
+    componentUsage: "component-usage",
+};
+const normalizeWithSlug = (withSlugFlag) => {
+    if (Array.isArray(withSlugFlag)) {
+        return withSlugFlag.filter(Boolean);
+    }
+    if (typeof withSlugFlag === "string" && withSlugFlag.length > 0) {
+        return [withSlugFlag];
+    }
+    return undefined;
+};
+const countSelectionModes = ({ all, withSlug, startsWith, }) => [
+    Boolean(all),
+    Boolean(withSlug && withSlug.length > 0),
+    Boolean(startsWith),
+].filter(Boolean).length;
+const assertValidSelection = ({ all, withSlug, startsWith, }) => {
+    const selectedModes = countSelectionModes({ all, withSlug, startsWith });
+    if (selectedModes === 0) {
+        throw new Error("Missing story selection. Pass exactly one of --all, --withSlug, or --startsWith.");
+    }
+    if (selectedModes > 1) {
+        throw new Error("Pass only one story selection mode: --all, --withSlug, or --startsWith.");
+    }
+};
+const printComponentUsageSummary = (report) => {
+    Logger.log("Component usage inspection");
+    Logger.log(`Space: ${report.spaceId}`);
+    Logger.log(`Query: ${report.queryName}`);
+    Logger.log(`Stories scanned: ${report.totals.storiesScanned}`);
+    Logger.log(`Stories matched: ${report.totals.storiesMatched}`);
+    Logger.log(`Total matches: ${report.totals.matches}`);
+    const countsByStory = report.matches.reduce((acc, match) => {
+        const slug = match.storyFullSlug || match.storySlug || "[unknown]";
+        acc[slug] = (acc[slug] || 0) + 1;
+        return acc;
+    }, {});
+    if (Object.keys(countsByStory).length === 0) {
+        Logger.warning("No matches found.");
+        return;
+    }
+    Logger.log("Matches by story:");
+    for (const [slug, count] of Object.entries(countsByStory)) {
+        Logger.log(`- ${slug}: ${count}`);
+    }
+};
+export const inspect = async (props) => {
+    const { input, flags } = props;
+    const command = input[1];
+    switch (command) {
+        case INSPECT_COMMANDS.componentUsage: {
+            const from = getFrom(flags, apiConfig);
+            const queryNameOrPath = flags["query"];
+            const withSlug = normalizeWithSlug(flags["withSlug"]);
+            const startsWith = flags["startsWith"] || undefined;
+            const all = Boolean(flags["all"]);
+            const outputPath = flags["outputPath"];
+            assertValidSelection({ all, withSlug, startsWith });
+            if (!queryNameOrPath) {
+                throw new Error("Missing query. Pass --query with a component usage query file name or path.");
+            }
+            const query = await loadComponentUsageQuery(queryNameOrPath);
+            const report = await inspectStoryblokStories({
+                query,
+                spaceId: from,
+                filters: {
+                    all: all || undefined,
+                    withSlug,
+                    startsWith,
+                },
+            }, apiConfig);
+            printComponentUsageSummary(report);
+            if (outputPath) {
+                await createAndSaveToFile({
+                    path: outputPath,
+                    res: report,
+                }, apiConfig);
+            }
+            break;
+        }
+        default:
+            throw new Error("Unknown inspect command. Supported command: component-usage.");
+    }
+};

package/dist/cli/index.js

@@ -1,6 +1,6 @@
 #! /usr/bin/env node
 import meow from "meow";
-import { backupDescription, debugDescription, mainDescription, syncDescription, removeDescription, initDescription, discoverDescription, migrateDescription, languagePublishStateDescription, storyVersionsDescription, publishedLayerExportDescription, revertDescription, migrationsDescription, copyDescription, } from "./cli-descriptions.js";
+import { backupDescription, debugDescription, mainDescription, syncDescription, removeDescription, initDescription, discoverDescription, inspectDescription, migrateDescription, languagePublishStateDescription, storyVersionsDescription, publishedLayerExportDescription, revertDescription, migrationsDescription, copyDescription, } from "./cli-descriptions.js";
 import { pipe, prop } from "./utils/cli-utils.js";
 const app = () => ({
     cli: meow(mainDescription, {
@@ -229,6 +229,38 @@ app.discover = () => ({
         await discover(cli);
     },
 });
+app.inspect = () => ({
+    cli: meow(inspectDescription, {
+        importMeta: import.meta,
+        booleanDefault: undefined,
+        flags: {
+            from: {
+                type: "string",
+            },
+            all: {
+                type: "boolean",
+                default: false,
+            },
+            withSlug: {
+                type: "string",
+                isMultiple: true,
+            },
+            startsWith: {
+                type: "string",
+            },
+            query: {
+                type: "string",
+            },
+            outputPath: {
+                type: "string",
+            },
+        },
+    }),
+    action: async (cli) => {
+        const { inspect } = await import("./commands/inspect.js");
+        await inspect(cli);
+    },
+});
 app.migrations = () => ({
     cli: meow(migrationsDescription, {
         importMeta: import.meta,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sb-mig",
-  "version": "6.1.1",
+  "version": "6.2.0",
   "description": "CLI to rule the world. (and handle stuff related to Storyblok CMS)",
   "author": "Marcin Krawczyk <marckraw@icloud.com>",
   "license": "MIT",