@canonical/pragma-cli 0.30.0 → 0.32.0

package/src/domains/standard/operations/lookup.ts

@@ -1,151 +0,0 @@
-/**
- * Look up detailed information for a single code standard by name.
- *
- * Queries the base standard data plus its dos and donts code blocks,
- * then assembles a {@link StandardDetailed} object.
- *
- * @param store - ke store to query
- * @param name - standard name (e.g. "react/component/folder-structure")
- * @returns full standard detail including dos/donts code blocks
- * @throws PragmaError.notFound if the standard does not exist
- * @note Queries ke store
- */
-
-import type { Store, URI } from "@canonical/ke";
-import { escapeSparqlValue } from "@canonical/ke";
-import { PragmaError } from "#error";
-import resolveUri from "../../graph/helpers/resolveUri.js";
-import { buildQuery } from "../../shared/buildQuery.js";
-import compactUri from "../../shared/compactUri.js";
-import { P } from "../../shared/prefixes.js";
-import {
-  detectCrossDomain,
-  listDomainNames,
-  suggestNames,
-} from "../../shared/suggestions/index.js";
-import type { CodeBlock, StandardDetailed } from "../../shared/types/index.js";
-
-export default async function lookupStandard(
-  store: Store,
-  nameOrUri: string,
-): Promise<StandardDetailed> {
-  const subjectClause = buildLookupSubjectClause(nameOrUri, store.prefixes);
-  const bindClause =
-    subjectClause === null ? "" : `BIND(${subjectClause} AS ?standard)`;
-  const matchClause =
-    subjectClause === null
-      ? `?standard ${P.cs}name ${escapeSparqlValue(nameOrUri)} .`
-      : "";
-
-  const baseResult = await store.query(
-    buildQuery(`
-      SELECT ?standard ?name ?categoryName ?description ?extends
-      WHERE {
-        ${bindClause}
-        ?standard a ${P.cs}CodeStandard ;
-                  ${P.cs}name ?name ;
-                  ${P.cs}description ?description .
-        ${matchClause}
-        OPTIONAL {
-          ?standard ${P.cs}hasCategory ?cat .
-          ?cat ${P.cs}slug ?categoryName .
-        }
-        OPTIONAL { ?standard ${P.cs}extends ?extends }
-      }
-      LIMIT 1
-    `),
-  );
-
-  if (baseResult.type !== "select" || baseResult.bindings.length === 0) {
-    const candidates = await listDomainNames(store, "standard");
-    const crossDomain = await detectCrossDomain(nameOrUri, "standard", store);
-    throw PragmaError.notFound("standard", nameOrUri, {
-      suggestions: suggestNames(nameOrUri, candidates),
-      recovery: {
-        message: "List available standards.",
-        cli: "pragma standard list",
-        mcp: { tool: "standard_list" },
-      },
-      crossDomain: crossDomain ?? undefined,
-    });
-  }
-
-  // Safe: length check above guarantees bindings[0] exists
-  const base = baseResult.bindings[0] as (typeof baseResult.bindings)[number];
-  const standardUri = base.standard;
-
-  // Fetch dos (cs:do → cs:Example with cs:description, cs:language, cs:code)
-  const dosResult = await store.query(
-    buildQuery(`
-      SELECT ?description ?language ?code
-      WHERE {
-        <${standardUri}> ${P.cs}do ?example .
-        OPTIONAL { ?example ${P.cs}description ?description }
-        OPTIONAL { ?example ${P.cs}language ?language }
-        OPTIONAL { ?example ${P.cs}code ?code }
-      }
-    `),
-  );
-
-  const dos: CodeBlock[] =
-    dosResult.type === "select"
-      ? dosResult.bindings.map((b) => ({
-          language: b.language ?? "typescript",
-          code: b.code ?? "",
-          caption: b.description,
-        }))
-      : [];
-
-  // Fetch donts (cs:dont → cs:Example with cs:description, cs:language, cs:code)
-  const dontsResult = await store.query(
-    buildQuery(`
-      SELECT ?description ?language ?code
-      WHERE {
-        <${standardUri}> ${P.cs}dont ?example .
-        OPTIONAL { ?example ${P.cs}description ?description }
-        OPTIONAL { ?example ${P.cs}language ?language }
-        OPTIONAL { ?example ${P.cs}code ?code }
-      }
-    `),
-  );
-
-  const donts: CodeBlock[] =
-    dontsResult.type === "select"
-      ? dontsResult.bindings.map((b) => ({
-          language: b.language ?? "typescript",
-          code: b.code ?? "",
-          caption: b.description,
-        }))
-      : [];
-
-  return {
-    uri: (standardUri ?? "") as URI,
-    name: base.name ?? nameOrUri,
-    category: base.categoryName ?? "",
-    description: base.description ?? "",
-    extends: base.extends
-      ? compactUri(base.extends, store.prefixes)
-      : undefined,
-    dos,
-    donts,
-  };
-}
-
-function buildLookupSubjectClause(
-  query: string,
-  prefixes: Readonly<Record<string, string>>,
-): string | null {
-  if (!looksLikeUri(query)) {
-    return null;
-  }
-
-  return `<${resolveUri(query, prefixes)}>`;
-}
-
-function looksLikeUri(query: string): boolean {
-  return (
-    query.startsWith("http://") ||
-    query.startsWith("https://") ||
-    query.includes(":")
-  );
-}

package/src/domains/standard/operations/sample.ts

@@ -1,35 +0,0 @@
-/**
- * Returns a small number of complete standard instances as exemplars.
- *
- * Composes the existing list and lookup operations to avoid duplicating
- * any SPARQL logic. Agents use this to learn the data shape before querying.
- *
- * @param store - ke store to query
- * @param count - number of samples (clamped 1–5, default 2)
- * @returns sample result with detailed standards and total count
- * @note Queries ke store
- */
-
-import type { Store } from "@canonical/ke";
-import pickRandom from "../../shared/pickRandom.js";
-import type {
-  SampleResult,
-  StandardDetailed,
-} from "../../shared/types/index.js";
-import listStandards from "./list.js";
-import lookupStandard from "./lookup.js";
-
-export default async function sampleStandards(
-  store: Store,
-  count = 2,
-): Promise<SampleResult<StandardDetailed>> {
-  const clamped = Math.max(1, Math.min(5, count));
-  const all = await listStandards(store);
-  const selected = pickRandom(all, clamped);
-
-  const samples = await Promise.all(
-    selected.map((s) => lookupStandard(store, s.name)),
-  );
-
-  return { samples, totalCount: all.length };
-}

package/src/domains/standard/orchestration/buildStandardFilters.ts

@@ -1,11 +0,0 @@
-import type { StandardListFilters } from "../../shared/types/index.js";
-
-export default function buildStandardFilters(params: {
-  category?: string;
-  search?: string;
-}): StandardListFilters {
-  return {
-    category: params.category,
-    search: params.search,
-  };
-}

package/src/domains/standard/orchestration/index.ts

@@ -1,4 +0,0 @@
-export { default as buildStandardFilters } from "./buildStandardFilters.js";
-export { default as resolveStandardList } from "./resolveStandardList.js";
-export { default as resolveStandardLookup } from "./resolveStandardLookup.js";
-export { default as standardEmptyError } from "./standardEmptyError.js";

package/src/domains/standard/orchestration/resolveStandardList.ts

@@ -1,45 +0,0 @@
-import type { ListParams } from "../../shared/contracts.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import type {
-  Disclosure,
-  StandardListFilters,
-} from "../../shared/types/index.js";
-import { listStandards, lookupStandard } from "../operations/index.js";
-import type { StandardListResolution } from "../types.js";
-import buildStandardFilters from "./buildStandardFilters.js";
-import standardEmptyError from "./standardEmptyError.js";
-
-export default async function resolveStandardList(
-  rt: Pick<PragmaRuntime, "store">,
-  params: ListParams & StandardListFilters,
-): Promise<StandardListResolution> {
-  const filters = buildStandardFilters(params);
-  const items = await listStandards(rt.store, filters);
-
-  if (items.length === 0) {
-    throw standardEmptyError(filters);
-  }
-
-  const disclosure: Disclosure = params.detailed
-    ? { level: "detailed" }
-    : params.digest
-      ? { level: "digest" }
-      : { level: "summary" };
-
-  const details =
-    disclosure.level === "summary"
-      ? undefined
-      : await Promise.all(
-          items.map((item) =>
-            lookupStandard(rt.store, item.name).catch(() => null),
-          ),
-        );
-
-  return {
-    params,
-    items,
-    filters,
-    disclosure,
-    details,
-  };
-}

package/src/domains/standard/orchestration/resolveStandardLookup.ts

@@ -1,33 +0,0 @@
-import type { LookupContract, LookupResult } from "../../shared/contracts.js";
-import lookupMany from "../../shared/lookupMany.js";
-import type { PragmaRuntime } from "../../shared/runtime.js";
-import { expandLookupQueries } from "../../shared/suggestions/index.js";
-import type { StandardDetailed } from "../../shared/types/index.js";
-import { lookupStandard } from "../operations/index.js";
-
-export default async function resolveStandardLookup(
-  store: Pick<PragmaRuntime, "store">["store"],
-  queries: readonly string[],
-): Promise<LookupContract<StandardDetailed>> {
-  const { names, globErrors } = await expandLookupQueries(
-    queries,
-    store,
-    "standard",
-  );
-
-  const lookupResult: LookupResult<StandardDetailed> =
-    names.length > 0
-      ? await lookupMany(names, (query) => lookupStandard(store, query))
-      : { results: [], errors: [], meta: { internalErrorCount: 0 } };
-
-  const result: LookupResult<StandardDetailed> = {
-    results: lookupResult.results,
-    errors: [...lookupResult.errors, ...globErrors],
-    meta: lookupResult.meta ?? { internalErrorCount: 0 },
-  };
-
-  return {
-    params: { names: queries },
-    result,
-  };
-}

package/src/domains/standard/orchestration/standardEmptyError.test.ts

@@ -1,33 +0,0 @@
-import { describe, expect, it } from "vitest";
-import standardEmptyError from "./standardEmptyError.js";
-
-describe("standardEmptyError", () => {
-  it("filter-narrowing: a category/search was active → clear filters and re-list", () => {
-    const err = standardEmptyError({ category: "react", search: "fold" });
-
-    expect(err.filters).toEqual({ category: "react", search: "fold" });
-    expect(err.recovery).toEqual({
-      message: "List all standards without filters.",
-      cli: "pragma standard list",
-      mcp: { tool: "standard_list" },
-    });
-  });
-
-  it("store-empty: no filter active → install, not a self-looping list", () => {
-    const err = standardEmptyError({});
-
-    expect(err.filters).toBeUndefined();
-    // Must NOT suggest `pragma standard list` again — that just re-returns empty.
-    expect(err.recovery).toEqual({
-      message: "Install the code standards packages that provide standards.",
-      cli: "bun add -D @canonical/code-standards",
-    });
-    expect(err.recovery?.mcp).toBeUndefined();
-  });
-
-  it("install branch cites the code-standards package", () => {
-    const err = standardEmptyError({});
-    expect(err.recovery?.cli).toContain("@canonical/code-standards");
-    expect(err.recovery?.cli).not.toContain("ds-global");
-  });
-});

package/src/domains/standard/orchestration/standardEmptyError.ts

@@ -1,29 +0,0 @@
-import { PragmaError } from "#error";
-import type { StandardListFilters } from "../../shared/types/index.js";
-
-export default function standardEmptyError(
-  filters: StandardListFilters,
-): PragmaError {
-  const active: Record<string, string> = {};
-  if (filters.category) active.category = filters.category;
-  if (filters.search) active.search = filters.search;
-  const hasFilter = Object.keys(active).length > 0;
-
-  return PragmaError.emptyResults("standard", {
-    filters: hasFilter ? active : undefined,
-    recovery: hasFilter
-      ? {
-          // Filter-narrowing: clear the active category/search and re-list.
-          message: "List all standards without filters.",
-          cli: "pragma standard list",
-          mcp: { tool: "standard_list" },
-        }
-      : {
-          // Store-empty with no filter active: suggesting `standard list`
-          // again would just re-return empty, so route to the install.
-          message:
-            "Install the code standards packages that provide standards.",
-          cli: "bun add -D @canonical/code-standards",
-        },
-  });
-}

package/src/domains/standard/standardConfig.ts

@@ -1,42 +0,0 @@
-import type { EntityDisplayConfig } from "../shared/contracts.js";
-import { P } from "../shared/prefixes.js";
-import type {
-  FilterConfig,
-  StandardDetailed,
-  StandardDigest,
-  StandardSummary,
-} from "../shared/types/index.js";
-
-/** Display-contract configuration for code-standard entities. */
-export const standardConfig: EntityDisplayConfig<
-  StandardSummary,
-  StandardDigest,
-  StandardDetailed
-> = {
-  domain: "standard",
-  entityName: "standard",
-  rdfTypes: [`${P.cs}CodeStandard`],
-  listColumns: [
-    { key: "uri", label: "IRI" },
-    { key: "name", label: "Name" },
-    { key: "category", label: "Category" },
-    { key: "description", label: "Description" },
-  ],
-  digestColumns: [{ key: "extends", label: "Extends", showWhenEmpty: false }],
-  lookupSections: [
-    { key: "description", heading: "Description", kind: "field" },
-    { key: "extends", heading: "Extends", kind: "field", showWhenEmpty: false },
-    { key: "dos", heading: "Do", kind: "table", showWhenEmpty: false },
-    { key: "donts", heading: "Don't", kind: "table", showWhenEmpty: false },
-  ],
-  emptyRecovery: (_filters: FilterConfig) => ({
-    message: "List available standards.",
-    cli: "pragma standard list",
-    mcp: { tool: "standard_list" },
-  }),
-  notFoundRecovery: (_query: string) => ({
-    message: "List available standards.",
-    cli: "pragma standard list",
-    mcp: { tool: "standard_list" },
-  }),
-};

package/src/domains/standard/stories.test.ts

@@ -1,24 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { standardListStory, standardLookupStory } from "./stories.js";
-
-describe("standardListStory", () => {
-  it("renders the ink list view", () => {
-    const view = standardListStory.renderInk?.({
-      items: [],
-      details: undefined,
-      disclosure: { level: "summary" },
-    });
-    expect(typeof view).toBe("string");
-    expect(view).toContain("Standards");
-  });
-});
-
-describe("standardLookupStory", () => {
-  it("renders the ink lookup view", () => {
-    const view = standardLookupStory.renderInk?.(
-      { results: [], errors: [] },
-      { surface: "cli", detailed: false, params: {} },
-    );
-    expect(typeof view).toBe("string");
-  });
-});

package/src/domains/standard/stories.ts

@@ -1,151 +0,0 @@
-/**
- * Standard read stories — the single declaration of `standard list` and
- * `standard lookup` for both surfaces.
- *
- * The story kernel compiles these into the CLI commands and MCP tools,
- * so descriptions, parameters, resolution, and rendering live here once.
- */
-
-import { createListView, createLookupView } from "#tui";
-import type { LookupStory, ReadStory } from "../shared/stories/index.js";
-import type { StandardDetailed } from "../shared/types/index.js";
-import {
-  createInkLookupOptions,
-  listFormatters,
-  lookupFormatters,
-  type StandardListOutput,
-  type StandardLookupInput,
-} from "./formatters/index.js";
-import {
-  resolveStandardList,
-  resolveStandardLookup,
-} from "./orchestration/index.js";
-import { standardConfig } from "./standardConfig.js";
-import type { StandardListResolution } from "./types.js";
-
-/** The `standard list` / `standard_list` read story. */
-export const standardListStory: ReadStory<
-  StandardListResolution,
-  StandardListOutput
-> = {
-  noun: "standard",
-  verb: "list",
-  description: "List all code standards",
-  toolDescription:
-    "List code standards. Optionally filter by category or search term. Use digest/detailed for progressive disclosure.",
-  params: [
-    {
-      name: "category",
-      type: "string",
-      description: "Filter by category",
-      toolDescription: "Filter by category name",
-    },
-    {
-      name: "search",
-      type: "string",
-      description: "Search in name and description",
-    },
-    {
-      name: "digest",
-      type: "boolean",
-      description: "Show description and first example for each standard",
-      default: false,
-    },
-    {
-      name: "detailed",
-      type: "boolean",
-      description: "Show full dos/donts for each standard",
-      default: false,
-    },
-  ],
-  examples: [
-    "pragma standard list",
-    "pragma standard list --category react",
-    'pragma standard list --search "folder"',
-    "pragma standard list --digest",
-    "pragma standard list --detailed",
-    "pragma standard list --llm",
-  ],
-  resolve: (rt, params) =>
-    resolveStandardList(rt, {
-      category: params.category as string | undefined,
-      search: params.search as string | undefined,
-      digest: params.digest === true,
-      detailed: params.detailed === true,
-    }),
-  toOutput: (resolution) => ({
-    items: resolution.items,
-    details: resolution.details,
-    disclosure: resolution.disclosure,
-  }),
-  formatters: listFormatters,
-  toEnvelope: (resolution) => {
-    if (resolution.disclosure.level === "summary") {
-      return {
-        data: resolution.items,
-        meta: { count: resolution.items.length },
-      };
-    }
-    const output: StandardListOutput = {
-      items: resolution.items,
-      details: resolution.details,
-      disclosure: resolution.disclosure,
-    };
-    return {
-      data: JSON.parse(listFormatters.json(output)),
-      meta: {
-        count: resolution.items.length,
-        disclosure: resolution.disclosure.level,
-      },
-    };
-  },
-  renderInk: (output) =>
-    createListView({
-      heading: "Standards",
-      domain: "standard",
-      items: output.items,
-      columns: standardConfig.listColumns,
-    }),
-};
-
-/** The `standard lookup` / `standard_lookup` read story. */
-export const standardLookupStory: LookupStory<
-  StandardDetailed,
-  StandardLookupInput
-> = {
-  noun: "standard",
-  description: "Look up detailed information for a standard by name or IRI",
-  toolDescription:
-    "Get detailed information about one or more code standards including dos and donts with code examples.",
-  namesDescription: "Standard names or IRIs",
-  namesToolDescription: "Standard names or IRIs to look up",
-  detailedParam: {
-    description: "Include dos and donts with code blocks",
-    toolDescription:
-      "Return full details with dos/donts (default: true for MCP)",
-  },
-  examples: [
-    "pragma standard lookup react/component/folder-structure",
-    "pragma standard lookup react/component/folder-structure react/component/props",
-    "pragma standard lookup react/component/folder-structure --detailed",
-    "pragma standard lookup react/component/folder-structure --llm",
-    "pragma standard lookup cs:react_props",
-  ],
-  resolve: async (rt, names) => {
-    const contract = await resolveStandardLookup(rt.store, names);
-    return contract.result;
-  },
-  toFmtInput: (standard, view) => ({ standard, detailed: view.detailed }),
-  formatters: lookupFormatters,
-  project: (standard) => {
-    const { uri, name, category, description } = standard;
-    return { uri, name, category, description };
-  },
-  renderInk: (result, view) =>
-    createLookupView({
-      results: result.results,
-      errors: result.errors,
-      domain: "standard",
-      options: createInkLookupOptions(view.detailed),
-    }),
-};

package/src/domains/standard/types.ts

@@ -1,15 +0,0 @@
-import type { ListParams } from "../shared/contracts.js";
-import type {
-  Disclosure,
-  StandardDetailed,
-  StandardListFilters,
-  StandardSummary,
-} from "../shared/types/index.js";
-
-export interface StandardListResolution {
-  readonly params: ListParams & StandardListFilters;
-  readonly items: readonly StandardSummary[];
-  readonly filters: StandardListFilters;
-  readonly disclosure: Disclosure;
-  readonly details?: readonly (StandardDetailed | null)[];
-}

package/src/domains/tier/commands/index.ts

@@ -1,3 +0,0 @@
-/** @module Re-exports tier command builders (`list`). */
-
-export { default as listCommand } from "./list.js";

package/src/domains/tier/commands/list.test.ts

@@ -1,67 +0,0 @@
-import type { CommandOutputResult } from "@canonical/cli-core";
-import type { Store } from "@canonical/ke";
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import { createTestStore, DS_ALL_TTL } from "#testing";
-import type { PragmaContext } from "../../shared/context.js";
-import listCommand from "./list.js";
-
-let store: Store;
-let cleanup: () => void;
-
-beforeAll(async () => {
-  const result = await createTestStore({ ttl: DS_ALL_TTL });
-  store = result.store;
-  cleanup = result.cleanup;
-});
-
-afterAll(() => cleanup());
-
-function makeCtx(
-  overrides?: Partial<PragmaContext["globalFlags"]>,
-): PragmaContext {
-  return {
-    cwd: "/tmp",
-    store,
-    config: { tier: undefined, channel: "normal" },
-    globalFlags: {
-      llm: false,
-      format: "text",
-      verbose: false,
-      ...overrides,
-    },
-  };
-}
-
-describe("tier list command", () => {
-  it("returns tiers with hierarchy", async () => {
-    const ctx = makeCtx();
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    expect(result.tag).toBe("output");
-
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("global");
-    expect(text).toContain("apps");
-    expect(text).toContain("apps/lxd");
-  });
-
-  it("renders flat tier list without parent references", async () => {
-    const ctx = makeCtx();
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).not.toContain("(parent:");
-  });
-
-  it("renders LLM format with --llm", async () => {
-    const ctx = makeCtx({ llm: true });
-    const cmd = listCommand(ctx);
-    const result = await cmd.execute({}, ctx);
-    const output = result as CommandOutputResult;
-    const text = output.render.plain(output.value);
-    expect(text).toContain("## Tiers");
-    expect(text).toContain("**global**");
-  });
-});

package/src/domains/tier/commands/list.ts

@@ -1,9 +0,0 @@
-import type { CommandDefinition } from "@canonical/cli-core";
-import type { PragmaContext } from "../../shared/context.js";
-import { compileReadCommand } from "../../shared/stories/index.js";
-import { tierListStory } from "../stories.js";
-
-/** Wire the `pragma tier list` CLI command from the tier list story. */
-export default function listCommand(ctx: PragmaContext): CommandDefinition {
-  return compileReadCommand(ctx, tierListStory);
-}

package/src/domains/tier/formatters/index.ts

@@ -1,3 +0,0 @@
-/** @module Re-exports tier formatters (`listFormatters`). */
-
-export { default as listFormatters } from "./list.js";