@cardstack/boxel-cli 0.2.0-unstable.448 → 0.3.0-unstable.13

package/bundled-types/host-app/commands/execute-atomic-operations.ts

@@ -0,0 +1,44 @@
+import { service } from '@ember/service';
+
+import type { AtomicOperation } from '@cardstack/runtime-common/atomic-document';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import type CardService from '../services/card-service';
+
+export default class ExecuteAtomicOperationsCommand extends HostBaseCommand<
+  typeof BaseCommandModule.ExecuteAtomicOperationsInput,
+  typeof BaseCommandModule.ExecuteAtomicOperationsResult
+> {
+  @service declare private cardService: CardService;
+
+  description = 'Execute atomic operations against a realm';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { ExecuteAtomicOperationsInput } = commandModule;
+    return ExecuteAtomicOperationsInput;
+  }
+
+  requireInputFields = ['realmIdentifier', 'operations'];
+
+  protected async run(
+    input: BaseCommandModule.ExecuteAtomicOperationsInput,
+  ): Promise<BaseCommandModule.ExecuteAtomicOperationsResult> {
+    let commandModule = await this.loadCommandModule();
+    const { ExecuteAtomicOperationsResult } = commandModule;
+    const results = await this.cardService.executeAtomicOperations(
+      input.operations as AtomicOperation[],
+      new URL(input.realmIdentifier),
+    );
+    const atomicResults = results['atomic:results'];
+    if (!Array.isArray(atomicResults)) {
+      const detail = (results as { errors?: Array<{ detail?: string }> })
+        .errors?.[0]?.detail;
+      throw new Error(detail ?? 'Atomic operations failed');
+    }
+    return new ExecuteAtomicOperationsResult({ results: atomicResults });
+  }
+}

package/bundled-types/host-app/commands/fetch-card-json.ts

@@ -0,0 +1,33 @@
+import { service } from '@ember/service';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import type CardService from '../services/card-service';
+
+export default class FetchCardJsonCommand extends HostBaseCommand<
+  typeof BaseCommandModule.FetchCardJsonInput,
+  typeof BaseCommandModule.FetchCardJsonResult
+> {
+  @service declare private cardService: CardService;
+
+  description = 'Fetch a card as a JSON document by URL';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { FetchCardJsonInput } = commandModule;
+    return FetchCardJsonInput;
+  }
+
+  requireInputFields = ['cardIdentifier'];
+
+  protected async run(
+    input: BaseCommandModule.FetchCardJsonInput,
+  ): Promise<BaseCommandModule.FetchCardJsonResult> {
+    let commandModule = await this.loadCommandModule();
+    const { FetchCardJsonResult } = commandModule;
+    const doc = await this.cardService.fetchJSON(input.cardIdentifier);
+    return new FetchCardJsonResult({ document: doc });
+  }
+}

package/bundled-types/host-app/commands/full-reindex-realm.ts

@@ -0,0 +1,30 @@
+import { service } from '@ember/service';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import type RealmService from '../services/realm';
+
+export default class FullReindexRealmCommand extends HostBaseCommand<
+  typeof BaseCommandModule.RealmIdentifierCard,
+  undefined
+> {
+  @service declare private realm: RealmService;
+
+  static actionVerb = 'Full Reindex';
+  description =
+    'Force a full realm reindex. This republishes a from-scratch indexing job after clearing indexed mtimes, so every file in the realm is revisited even if mtimes have not changed. Use this when the user suspects indexing drift, stale cached results, or wants a full rebuild instead of the lighter default reindex. A user may request that they want to perform a full or deep reload/refresh of a realm in order to fully reindex it.';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { RealmIdentifierCard } = commandModule;
+    return RealmIdentifierCard;
+  }
+
+  protected async run(
+    input: BaseCommandModule.RealmIdentifierCard,
+  ): Promise<undefined> {
+    await this.realm.fullReindex(input.realmIdentifier);
+  }
+}

package/bundled-types/host-app/commands/generate-example-cards.ts

@@ -0,0 +1,298 @@
+import { service } from '@ember/service';
+
+import {
+  isCardInstance,
+  type LooseSingleCardDocument,
+} from '@cardstack/runtime-common';
+import {
+  codeRefWithAbsoluteIdentifier,
+  isResolvedCodeRef,
+  type ResolvedCodeRef,
+} from '@cardstack/runtime-common/code-ref';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import {
+  buildAttachedFileURLs,
+  buildExamplePrompt,
+  ONE_SHOT_SYSTEM_PROMPT,
+  parseExamplePayloadFromOutput,
+} from '../lib/example-card-helpers';
+import HostBaseCommand from '../lib/host-base-command';
+
+import { prettifyPrompts } from '../utils/prettify-prompts';
+
+import OneShotLlmRequestCommand from './one-shot-llm-request';
+import SendAiAssistantMessageCommand from './send-ai-assistant-message';
+
+import type AiAssistantPanelService from '../services/ai-assistant-panel-service';
+import type CardService from '../services/card-service';
+import type MatrixService from '../services/matrix-service';
+import type RealmService from '../services/realm';
+import type StoreService from '../services/store';
+
+export default class GenerateExampleCardsCommand extends HostBaseCommand<
+  typeof BaseCommandModule.CreateInstancesInput,
+  undefined
+> {
+  @service declare private aiAssistantPanelService: AiAssistantPanelService;
+  @service declare private matrixService: MatrixService;
+  @service declare private realm: RealmService;
+
+  static actionVerb = 'Generate Example Cards';
+  description = 'Create new cards populated with sample data';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { CreateInstancesInput } = commandModule;
+    return CreateInstancesInput;
+  }
+
+  protected getPrompt(count: number) {
+    return `Generate ${count} additional instances of the specified card definition, populated with sample data.`;
+  }
+
+  protected getAttachedFileURLs(input: BaseCommandModule.CreateInstancesInput) {
+    return buildAttachedFileURLs(input.codeRef?.module);
+  }
+
+  protected async run(
+    input: BaseCommandModule.CreateInstancesInput,
+  ): Promise<undefined> {
+    if (!input.codeRef) {
+      throw new Error('Module is required');
+    }
+    let realm = input.realm || this.realm.defaultWritableRealm?.path;
+
+    await this.aiAssistantPanelService.openPanel();
+
+    const userPrompt = this.getPrompt(input.count || 1);
+    console.debug(
+      prettifyPrompts({
+        scope: 'GenerateExample:Panel',
+        systemPrompt: '(handled by AI assistant room)',
+        userPrompt,
+      }),
+    );
+
+    let sendMessageCommand = new SendAiAssistantMessageCommand(
+      this.commandContext,
+    );
+
+    await sendMessageCommand.execute({
+      roomId: this.matrixService.currentRoomId,
+      prompt: userPrompt,
+      attachedCards: input.exampleCard ? [input.exampleCard] : [],
+      attachedFileIdentifiers: this.getAttachedFileURLs(input),
+      realmIdentifier: realm,
+    });
+  }
+}
+
+export class GenerateExampleCardsOneShotCommand extends HostBaseCommand<
+  typeof BaseCommandModule.CreateInstancesInput,
+  typeof BaseCommandModule.CreateInstanceResult
+> {
+  @service declare private realm: RealmService;
+  @service declare private store: StoreService;
+  @service declare private cardService: CardService;
+
+  static actionVerb = 'Generate Example (One-shot)';
+
+  description =
+    'Create a new card instance populated with sample data via a direct LLM request';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { CreateInstancesInput } = commandModule;
+    return CreateInstancesInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.CreateInstancesInput,
+  ): Promise<BaseCommandModule.CreateInstanceResult> {
+    if (!input.codeRef) {
+      throw new Error('Module is required');
+    }
+
+    const realm = input.realm || this.realm.defaultWritableRealm?.path;
+
+    const promptSections = [
+      buildExamplePrompt(1, input.codeRef),
+      `Card definition module: ${input.codeRef.module}`,
+    ];
+
+    if (realm) {
+      promptSections.push(`Use realm URL ${realm} when generating any links.`);
+    }
+
+    const exampleCard = input.exampleCard as CardDef | undefined;
+    if (exampleCard?.id) {
+      promptSections.push(
+        `Existing example card id: ${exampleCard.id}. Provide fresh sample data that differs from this instance.`,
+      );
+    }
+    let serializedExampleJson: string | undefined;
+    if (exampleCard && isCardInstance(exampleCard)) {
+      try {
+        const serialized = await this.cardService.serializeCard(exampleCard);
+        serializedExampleJson = JSON.stringify(serialized?.data, null, 2);
+      } catch (error) {
+        console.warn('Failed to serialize current example card', { error });
+      }
+    }
+    if (serializedExampleJson) {
+      promptSections.push(
+        `Existing example card JSON:\n${serializedExampleJson}`,
+      );
+    }
+
+    const userPrompt = promptSections.join('\n\n');
+    console.debug(
+      prettifyPrompts({
+        scope: 'GenerateExample:OneShot',
+        systemPrompt: ONE_SHOT_SYSTEM_PROMPT,
+        userPrompt,
+      }),
+    );
+
+    const oneShot = new OneShotLlmRequestCommand(this.commandContext);
+    const attachedFileIdentifiers = buildAttachedFileURLs(input.codeRef.module);
+    const llmResult = await oneShot.execute({
+      codeRef: input.codeRef,
+      systemPrompt: ONE_SHOT_SYSTEM_PROMPT,
+      userPrompt,
+      llmModel: 'anthropic/claude-3-haiku',
+      attachedFileIdentifiers:
+        attachedFileIdentifiers.length > 0
+          ? attachedFileIdentifiers
+          : undefined,
+    });
+
+    const { payload: examplePayload } = parseExamplePayloadFromOutput(
+      llmResult.output,
+    );
+    if (!examplePayload) {
+      throw new Error('LLM did not return a valid JSON example payload');
+    }
+    const createdCard = await createExampleInstanceFromPayload({
+      codeRef: input.codeRef,
+      examplePayload,
+      realm,
+      store: this.store,
+      defaultRealm: this.realm.defaultWritableRealm?.path,
+      localDir: undefined,
+    }).catch((error) => {
+      console.warn('Failed to create generated example card', {
+        codeRef: input.codeRef,
+        realm,
+        error,
+      });
+      return undefined;
+    });
+    if (!createdCard) {
+      throw new Error('Failed to create generated example card');
+    }
+
+    const commandModule = await this.loadCommandModule();
+    const { CreateInstanceResult } = commandModule;
+    return new CreateInstanceResult({ createdCard });
+  }
+}
+
+export async function createExampleInstanceFromPayload(opts: {
+  codeRef: BaseCommandModule.CreateInstancesInput['codeRef'];
+  examplePayload: Record<string, unknown>;
+  realm: string | undefined;
+  store: StoreService;
+  defaultRealm?: string;
+  localDir?: string | null;
+}): Promise<CardDef | undefined> {
+  if (!opts.codeRef?.module || !opts.codeRef?.name) {
+    return undefined;
+  }
+  const resolvedRef = resolveExampleCodeRef(opts.codeRef, opts.realm);
+  if (!resolvedRef) {
+    return undefined;
+  }
+
+  const attributes = normalizeExampleAttributes(opts.examplePayload);
+
+  const doc: LooseSingleCardDocument = {
+    data: {
+      type: 'card',
+      attributes,
+      meta: {
+        adoptsFrom: resolvedRef,
+      },
+    },
+  };
+
+  const creationResult = await opts.store.add(doc, {
+    realm: opts.realm ?? opts.defaultRealm,
+    localDir: opts.localDir ?? undefined,
+    doNotWaitForPersist: true,
+  });
+  if (!isCardInstance(creationResult)) {
+    console.warn('Failed to save generated example card', {
+      errors: creationResult,
+    });
+    return undefined;
+  }
+  return creationResult;
+}
+
+function normalizeExampleAttributes(
+  examplePayload: Record<string, unknown>,
+): Record<string, unknown> {
+  let attributesSource: Record<string, unknown> | undefined;
+  if (
+    examplePayload.attributes &&
+    typeof examplePayload.attributes === 'object' &&
+    !Array.isArray(examplePayload.attributes)
+  ) {
+    attributesSource = examplePayload.attributes as Record<string, unknown>;
+  } else if (
+    examplePayload.data &&
+    typeof examplePayload.data === 'object' &&
+    !Array.isArray(examplePayload.data)
+  ) {
+    let dataNode = examplePayload.data as Record<string, unknown>;
+    if (
+      dataNode.attributes &&
+      typeof dataNode.attributes === 'object' &&
+      !Array.isArray(dataNode.attributes)
+    ) {
+      attributesSource = dataNode.attributes as Record<string, unknown>;
+    } else {
+      attributesSource = dataNode;
+    }
+  } else if (typeof examplePayload === 'object' && examplePayload) {
+    attributesSource = examplePayload as Record<string, unknown>;
+  }
+  let attributes = attributesSource ? { ...attributesSource } : {};
+  delete (attributes as any).id;
+  delete (attributes as any).relationships;
+  delete (attributes as any).meta;
+  return attributes;
+}
+
+function resolveExampleCodeRef(
+  codeRef: BaseCommandModule.CreateInstancesInput['codeRef'],
+  realm: string | undefined,
+): ResolvedCodeRef | undefined {
+  if (isResolvedCodeRef(codeRef)) {
+    return codeRef;
+  }
+  try {
+    const relativeTo = realm ? new URL(realm) : undefined;
+    const resolved = codeRefWithAbsoluteIdentifier(
+      codeRef,
+      relativeTo,
+    ) as ResolvedCodeRef;
+    return resolved;
+  } catch {
+    return undefined;
+  }
+}

package/bundled-types/host-app/commands/generate-readme-spec.ts

@@ -0,0 +1,116 @@
+import { service } from '@ember/service';
+
+import type { RealmResourceIdentifier } from '@cardstack/runtime-common';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+import type { SpecType } from 'https://cardstack.com/base/spec';
+
+import HostBaseCommand from '../lib/host-base-command';
+import { devSkillId } from '../lib/utils';
+
+import OneShotLlmRequestCommand from './one-shot-llm-request';
+import PatchCardInstanceCommand from './patch-card-instance';
+
+import type CommandService from '../services/command-service';
+
+export default class GenerateReadmeSpecCommand extends HostBaseCommand<
+  typeof BaseCommandModule.GenerateReadmeSpecInput,
+  typeof BaseCommandModule.GenerateReadmeSpecResult
+> {
+  @service declare private commandService: CommandService;
+
+  private static getUserPrompt(
+    ref: {
+      name: string;
+      module: string;
+    },
+    specType: SpecType,
+  ) {
+    return `Generate README documentation for a spec of type ${specType} that has code ref of (name:${ref.name}, module:${ref.module}). Show how to import and use it in inside a consuming card.`;
+  }
+  private static SYSTEM_PROMPT = `YOU ARE a bot responsible to Github README documentation for specs/code.
+
+Reference the Spec Documentation inside boxel-development skill for understanding spec types, but focus ONLY on crafting usage documentation. Based upon specType, create documentation with these 4 sections:
+
+• **Summary**: Brief summary of what the spec does
+• **Import**: Show the ES6 import statmenet of the spec. Omit .gts extension.
+• **Usage as a Field**: Show how to use the spec as a field within a consuming card/field. Only display this section for card or field.
+• **Template Usage**: Show how to invoke the spec inside a template within a consuming card/field
+
+Requirements:
+- Keep examples simple and practical
+- DO NOT include title headers
+`;
+
+  static actionVerb = 'Generate README for Spec';
+  description =
+    'Generate a README for a spec and patch it to the spec readMe field';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { GenerateReadmeSpecInput } = commandModule;
+    return GenerateReadmeSpecInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.GenerateReadmeSpecInput,
+  ): Promise<BaseCommandModule.GenerateReadmeSpecResult> {
+    if (!input.spec) {
+      throw new Error('Spec is required');
+    }
+
+    // Generate the README using the existing command
+    const generateReadmeCommand = new OneShotLlmRequestCommand(
+      this.commandService.commandContext,
+    );
+
+    let userPrompt = GenerateReadmeSpecCommand.getUserPrompt(
+      input.spec.ref,
+      input.spec.specType as SpecType,
+    );
+    let systemPrompt = GenerateReadmeSpecCommand.SYSTEM_PROMPT;
+
+    const result = await generateReadmeCommand.execute({
+      codeRef: {
+        name: input.spec.ref.name,
+        module: input.spec.moduleHref as RealmResourceIdentifier,
+      },
+      userPrompt,
+      systemPrompt,
+      llmModel: 'anthropic/claude-3-haiku',
+      skillCardIds: [devSkillId],
+    });
+
+    // Patch the spec's readMe field
+    if (input.spec.id) {
+      try {
+        const patchCardInstanceCommand = new PatchCardInstanceCommand(
+          this.commandService.commandContext,
+          { cardType: input.spec.constructor as typeof CardDef }, //is this correct?
+        );
+
+        await patchCardInstanceCommand.execute({
+          cardId: input.spec.id,
+          patch: {
+            attributes: {
+              readMe: result.output,
+            },
+          },
+        });
+
+        console.log('README generated and spec updated successfully');
+      } catch (patchError) {
+        console.warn('README generated but could not update spec:', patchError);
+        // Still return the generated result even if patching fails
+      }
+    }
+
+    let commandModule = await this.loadCommandModule();
+    const { GenerateReadmeSpecResult } = commandModule;
+
+    return new GenerateReadmeSpecResult({
+      readme: result.output,
+    });
+  }
+}

package/bundled-types/host-app/commands/generate-theme-example.ts

@@ -0,0 +1,147 @@
+import { service } from '@ember/service';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import {
+  buildAttachedFileURLs,
+  buildExamplePrompt,
+  ONE_SHOT_SYSTEM_PROMPT,
+  parseExamplePayloadFromOutput,
+} from '../lib/example-card-helpers';
+import HostBaseCommand from '../lib/host-base-command';
+
+import { createExampleInstanceFromPayload } from './generate-example-cards';
+import OneShotLlmRequestCommand from './one-shot-llm-request';
+
+import type RealmService from '../services/realm';
+import type StoreService from '../services/store';
+
+export default class GenerateThemeExampleCommand extends HostBaseCommand<
+  typeof BaseCommandModule.GenerateThemeExampleInput,
+  typeof BaseCommandModule.CreateInstanceResult
+> {
+  @service declare private store: StoreService;
+  @service declare private realm: RealmService;
+
+  static actionVerb = 'Create Theme Example';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { GenerateThemeExampleInput } = commandModule;
+    return GenerateThemeExampleInput;
+  }
+
+  protected async run(
+    input: BaseCommandModule.GenerateThemeExampleInput,
+  ): Promise<BaseCommandModule.CreateInstanceResult> {
+    if (!input.codeRef) {
+      throw new Error('codeRef is required to create a card');
+    }
+    const realm = input.realm || this.realm.defaultWritableRealm?.path;
+    if (!realm) {
+      throw new Error('realm is required to create a card');
+    }
+
+    // Build the prompt and attachments for the LLM
+    const promptSections = [buildExamplePrompt(1, input.codeRef)];
+    if (input.prompt && input.prompt.trim().length) {
+      promptSections.push(input.prompt.trim());
+    }
+    let guidance = this.guidanceForCodeRef(input.codeRef);
+    if (guidance) {
+      promptSections.push(guidance);
+    }
+    const userPrompt = promptSections.join('\n\n');
+    const llmModel = input.llmModel || 'anthropic/claude-3-haiku';
+    const attachedFileIdentifiers = input.codeRef.module
+      ? buildAttachedFileURLs(input.codeRef.module)
+      : [];
+    const skillCardIds = Array.from(
+      new Set(
+        [
+          input.skillCard?.id,
+          ...(Array.isArray(input.skillCardIds) ? input.skillCardIds : []),
+        ].filter(
+          (id): id is string => typeof id === 'string' && id.trim().length > 0,
+        ),
+      ),
+    );
+
+    const oneShot = new OneShotLlmRequestCommand(this.commandContext);
+    const llmResult = await oneShot.execute({
+      codeRef: input.codeRef,
+      systemPrompt: ONE_SHOT_SYSTEM_PROMPT,
+      userPrompt,
+      llmModel,
+      attachedFileIdentifiers: attachedFileIdentifiers.length
+        ? attachedFileIdentifiers
+        : undefined,
+      skillCardIds,
+    });
+
+    const { payload: examplePayload } = parseExamplePayloadFromOutput(
+      llmResult.output,
+    );
+    if (!examplePayload) {
+      throw new Error('LLM did not return a valid JSON example payload');
+    }
+
+    const createdCard = await createExampleInstanceFromPayload({
+      codeRef: input.codeRef,
+      examplePayload: examplePayload as Record<string, unknown>,
+      realm,
+      store: this.store,
+      defaultRealm: this.realm.defaultWritableRealm?.path,
+      localDir: input.localDir ?? null,
+    });
+
+    if (!createdCard) {
+      throw new Error('Failed to create theme example card');
+    }
+
+    let commandModule = await this.loadCommandModule();
+    const { CreateInstanceResult } = commandModule;
+    return new CreateInstanceResult({
+      createdCard: createdCard as CardDef,
+    });
+  }
+
+  private guidanceForCodeRef(codeRef: { module?: string | URL | null } | null) {
+    let moduleString = codeRef?.module?.toString() ?? '';
+    if (moduleString.includes('style-reference')) {
+      return this.styleReferenceGuidance();
+    }
+    if (moduleString.includes('brand-guide')) {
+      return this.brandGuideGuidance();
+    }
+    if (moduleString.includes('structured-theme')) {
+      return this.structuredThemeGuidance();
+    }
+    return null;
+  }
+
+  private structuredThemeGuidance(): string {
+    return [
+      'Structured Theme guidance: emit cssVariables with :root, .dark, and an `@theme inline` mapping back to Boxel tokens.',
+      'Keep palette, typography, spacing, radius, chart, sidebar, and shadow tokens cohesive across light/dark with OKLCH or Hex values that meet AA contrast.',
+      'Mirror values in `rootVariables` and `darkModeVariables`; use `var(--token, fallback)` and include remote fonts in `cssImports`.',
+    ].join('\n');
+  }
+
+  private styleReferenceGuidance(): string {
+    return [
+      'Style Reference guidance: describe the vibe via `styleName`, `visualDNA`, inspirations, wallpapers, and card metadata while carrying structured theme tokens.',
+      'Maintain cohesive light/dark palettes, typography, spacing, radius, and shadows with OKLCH or Hex values that satisfy AA contrast.',
+      'Emit `cssVariables` with :root, .dark, and `@theme inline` mappings that match variable maps; prefer `var(--token, fallback)` and include remote fonts in `cssImports`.',
+    ].join('\n');
+  }
+
+  private brandGuideGuidance(): string {
+    return [
+      'Brand Guide guidance: convey brand essence via `styleName`, `visualDNA`, inspirations, wall imagery, and marks/typography/palettes.',
+      'Populate marks, typography, palette, and semantic colors with cohesive OKLCH or Hex values that preserve AA contrast across light/dark.',
+      'Emit `cssVariables` covering :root, .dark, and `@theme inline` mappings; use `var(--token, fallback)` and capture fonts inside `cssImports`.',
+    ].join('\n');
+  }
+}