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

package/bundled-types/host-app/commands/create-specs.ts

@@ -0,0 +1,422 @@
+import { service } from '@ember/service';
+
+import {
+  loadCardDef,
+  specRef,
+  type RealmResourceIdentifier,
+  type ResolvedCodeRef,
+  isCardDef,
+  isFieldDef,
+  isSpecCard,
+  type Query,
+  type Loader,
+  getAncestor,
+} from '@cardstack/runtime-common';
+
+import {
+  codeRefWithAbsoluteIdentifier,
+  isResolvedCodeRef,
+} from '@cardstack/runtime-common/code-ref';
+
+import type { BaseDef, CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+import type { Spec } from 'https://cardstack.com/base/spec';
+import type { SpecType } from 'https://cardstack.com/base/spec';
+
+import HostBaseCommand from '../lib/host-base-command';
+import {
+  type CardOrFieldDeclaration,
+  type ModuleDeclaration,
+  isCardOrFieldDeclaration,
+  isReexportCardOrField,
+} from '../services/module-contents-service';
+
+import GenerateReadmeSpecCommand from './generate-readme-spec';
+
+import type CardService from '../services/card-service';
+import type ModuleContentsService from '../services/module-contents-service';
+import type RealmService from '../services/realm';
+import type StoreService from '../services/store';
+
+class SpecTypeGuesser {
+  constructor(private declaration: ModuleDeclaration) {}
+
+  get type(): SpecType | undefined {
+    return this.guess(this.declaration);
+  }
+
+  private guess(declaration: ModuleDeclaration): SpecType | undefined {
+    // Check if it's a card or field declaration
+    if (isCardOrFieldDeclaration(declaration)) {
+      // Check if it's a field definition
+      if (isFieldDef(declaration.cardOrField)) {
+        return 'field';
+      }
+
+      // Check if it's a card definition
+      if (isCardDef(declaration.cardOrField)) {
+        if (this.isApp(declaration)) {
+          return 'app';
+        }
+        return 'card';
+      }
+    }
+
+    // Check if it's a component
+    if (this.isComponent(declaration)) {
+      return 'component';
+    }
+
+    // Check if it's a command
+    if (this.isCommand(declaration)) {
+      return 'command';
+    }
+
+    return;
+  }
+
+  private isApp(declaration: CardOrFieldDeclaration): boolean {
+    if (declaration.exportName === 'AppCard') {
+      return true;
+    }
+    if (declaration.super) {
+      return (
+        declaration.super.type === 'external' &&
+        declaration.super.name === 'AppCard'
+      );
+    }
+    return false;
+  }
+
+  private isComponent(declaration: ModuleDeclaration): boolean {
+    if (
+      !('super' in declaration) ||
+      !declaration.super ||
+      declaration.super.type !== 'external'
+    ) {
+      return false;
+    }
+    const superName = declaration.super.name;
+    const superModule = declaration.super.module;
+    return (
+      superModule === '@glimmer/component' ||
+      (superName === 'Component' &&
+        superModule === 'https://cardstack.com/base/card-api') ||
+      superName === 'GlimmerComponent' ||
+      superName?.includes('Component')
+    );
+  }
+
+  private isCommand(declaration: ModuleDeclaration): boolean {
+    if (
+      !('super' in declaration) ||
+      !declaration.super ||
+      declaration.super.type !== 'external'
+    ) {
+      return false;
+    }
+    const superName = declaration.super.name;
+    return (
+      superName === 'Command' ||
+      superName === 'HostBaseCommand' ||
+      superName?.includes('Command')
+    );
+  }
+}
+interface CreateSpecResult {
+  spec: Spec;
+  new: boolean;
+}
+
+export default class CreateSpecCommand extends HostBaseCommand<
+  typeof BaseCommandModule.CreateSpecsInput,
+  typeof BaseCommandModule.CreateSpecsResult
+> {
+  @service declare private store: StoreService;
+  @service declare private cardService: CardService;
+  @service declare private moduleContentsService: ModuleContentsService;
+  @service declare private realm: RealmService;
+
+  static actionVerb = 'Create';
+  requireInputFields = ['targetRealm'];
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { CreateSpecsInput } = commandModule;
+    return CreateSpecsInput;
+  }
+
+  private async createSpec(
+    declaration: ModuleDeclaration,
+    codeRef: ResolvedCodeRef,
+    targetRealm: string,
+    SpecKlass: typeof CardDef,
+    createIfExists: boolean = false,
+    autoGenerateReadme: boolean = false,
+  ): Promise<CreateSpecResult> {
+    if (
+      isCardOrFieldDeclaration(declaration) &&
+      isSpecCard(declaration.cardOrField)
+    ) {
+      throw new Error('Cannot create a spec from another spec');
+    }
+    const cardTitle = this.getSpecTitle(declaration, codeRef.name);
+    const specType = new SpecTypeGuesser(declaration).type;
+
+    const ResolvedSpecClass = await getSpecClassFromDeclaration(
+      codeRef,
+      SpecKlass,
+      this.loaderService.loader,
+      targetRealm,
+    );
+    let createdSpecRes: CreateSpecResult;
+    if (!createIfExists) {
+      // Check if a spec already exists for this code ref
+      const existingSpecsQuery: Query = {
+        filter: {
+          on: specRef,
+          eq: {
+            ref: codeRef,
+          },
+        },
+      };
+
+      const existingSpecs = await this.store.search(existingSpecsQuery, [
+        targetRealm,
+      ]);
+      if (existingSpecs.length > 0) {
+        console.warn(`Spec already exists for ${cardTitle}, skipping`);
+        let savedSpec = existingSpecs[0] as Spec;
+        createdSpecRes = { spec: savedSpec, new: false };
+      } else {
+        let spec = new ResolvedSpecClass({
+          specType,
+          ref: codeRef,
+          cardTitle,
+        }) as Spec;
+        let savedSpec = (await this.store.add<Spec>(spec, {
+          realm: targetRealm,
+        })) as Spec;
+        createdSpecRes = { spec: savedSpec, new: true };
+      }
+    } else {
+      let spec = new ResolvedSpecClass({
+        specType,
+        ref: codeRef,
+        cardTitle,
+      }) as Spec;
+
+      let savedSpec = (await this.store.add<Spec>(spec, {
+        realm: targetRealm,
+      })) as Spec;
+      createdSpecRes = { spec: savedSpec, new: true };
+    }
+
+    if (!createdSpecRes.spec) {
+      throw new Error('Failed to create or retrieve spec');
+    }
+
+    let canEdit = this.realm.canWrite(targetRealm);
+    if (!canEdit) {
+      throw new Error(
+        `Cannot generate README without write access to ${targetRealm}`,
+      );
+    }
+    if (autoGenerateReadme && !createdSpecRes.spec.readMe) {
+      // we populate the readme when is not already set even when spec is already created
+      let generateReadmeSpecCommand = new GenerateReadmeSpecCommand(
+        this.commandContext,
+      );
+      await generateReadmeSpecCommand.execute({
+        spec: createdSpecRes.spec,
+      });
+    }
+
+    return createdSpecRes;
+  }
+
+  private getSpecTitle(
+    declaration: ModuleDeclaration,
+    fallbackName: string,
+  ): string {
+    if (
+      isCardOrFieldDeclaration(declaration) ||
+      isReexportCardOrField(declaration)
+    ) {
+      return declaration.cardOrField.displayName ?? fallbackName;
+    }
+
+    return fallbackName;
+  }
+
+  protected async run(
+    input: BaseCommandModule.CreateSpecsInput,
+  ): Promise<BaseCommandModule.CreateSpecsResult> {
+    let { codeRef, targetRealm, module, autoGenerateReadme } = input;
+
+    if (!targetRealm) {
+      throw new Error('targetRealm is required');
+    }
+
+    let url: string;
+    if (codeRef) {
+      let relativeTo = new URL(targetRealm);
+      let maybeAbsoluteRef = codeRefWithAbsoluteIdentifier(codeRef, relativeTo);
+      if (isResolvedCodeRef(maybeAbsoluteRef)) {
+        codeRef = maybeAbsoluteRef;
+      }
+      url = codeRef.module;
+    } else if (module) {
+      url = module;
+    } else {
+      throw new Error('Either codeRef or module must be provided');
+    }
+
+    let declarations = await this.moduleContentsService.assemble(url);
+    let SpecKlass = (await loadCardDef(specRef, {
+      loader: this.loaderService.loader,
+    })) as typeof CardDef;
+
+    let specs: Spec[] = [];
+    let newSpecs: Spec[] = [];
+
+    if (codeRef?.name) {
+      // Single spec generation when codeRef.name is provided
+      const declaration = declarations.find(
+        (decl) =>
+          decl.exportName === codeRef.name || decl.localName === codeRef.name,
+      );
+
+      if (!declaration) {
+        throw new Error(
+          `Could not find declaration for ${codeRef.name} in ${codeRef.module}`,
+        );
+      }
+
+      const savedSpec = await this.createSpec(
+        declaration,
+        codeRef,
+        targetRealm,
+        SpecKlass,
+        false,
+        autoGenerateReadme ?? false,
+      );
+
+      if (savedSpec.new) {
+        newSpecs.push(savedSpec.spec);
+      }
+      specs.push(savedSpec.spec);
+    } else {
+      // Multiple specs generation when codeRef.name is not provided
+      const specPromises = declarations.map(async (declaration) => {
+        let name = declaration.exportName || declaration.localName;
+        if (!name) {
+          throw new Error('declaration no name');
+        }
+        let specCodeRef: ResolvedCodeRef = {
+          module: url.replace('.gts', '') as RealmResourceIdentifier, // Remember to remove .gts extension
+          name,
+        };
+
+        try {
+          return await this.createSpec(
+            declaration,
+            specCodeRef,
+            targetRealm,
+            SpecKlass,
+            false,
+            false,
+            // intentionally not generating readme for multiple spec creation
+          );
+        } catch (e) {
+          console.warn(
+            `Failed to create spec for ${declaration.exportName || declaration.localName}:`,
+            e,
+          );
+          return null;
+        }
+      });
+
+      const promises = await Promise.all(specPromises);
+      const successfulPromises = promises.filter(
+        (p): p is CreateSpecResult => p !== null,
+      );
+      newSpecs.push(
+        ...successfulPromises.filter((r) => r?.new).map((r) => r.spec),
+      );
+      specs.push(...successfulPromises.map((r) => r.spec));
+    }
+
+    try {
+      let commandModule = await this.loadCommandModule();
+      const { CreateSpecsResult } = commandModule;
+      return new CreateSpecsResult({
+        newSpecs,
+        specs,
+      });
+    } catch (e) {
+      console.error('Error creating specs:', e);
+      throw e;
+    }
+  }
+}
+
+/**
+ * Finds the appropriate Spec class to use when creating a spec instance.
+ *
+ * @param codeRef - Code reference of the code being documented (used for naming convention)
+ * @param fallbackSpecClass - Base Spec class to use if no subclass found
+ * @param loader - Module loader for dynamically loading Spec subclasses
+ * @param targetRealm - Realm URL to use as relativeTo for loading the spec class
+ * @returns Spec subclass if found, otherwise fallback base Spec
+ */
+async function getSpecClassFromDeclaration(
+  codeRef: ResolvedCodeRef,
+  fallbackSpecClass: typeof CardDef,
+  loader: Loader,
+  targetRealm: string,
+): Promise<typeof CardDef> {
+  try {
+    const specCodeRef: ResolvedCodeRef = {
+      module: codeRef.module,
+      name: codeRef.name,
+    };
+    const loadedSpec = await loadCardDef(specCodeRef, {
+      loader,
+      relativeTo: new URL(targetRealm),
+    });
+
+    if (
+      loadedSpec &&
+      isCardDef(loadedSpec) &&
+      loadedSpec !== fallbackSpecClass &&
+      isSpecSubclass(loadedSpec, fallbackSpecClass)
+    ) {
+      return loadedSpec;
+    }
+  } catch {
+    // Spec subclass doesn't exist; fall back to base Spec
+  }
+
+  return fallbackSpecClass;
+}
+
+/**
+ * Checks if candidate class extends ancestor class via prototype chain.
+ * Both candidate and ancestor are CardDefs (Specs are Cards, not Fields).
+ * getAncestor returns typeof BaseDef, so we use that for the internal traversal.
+ */
+function isSpecSubclass(
+  candidate: typeof CardDef,
+  ancestor: typeof CardDef,
+): boolean {
+  let current: typeof BaseDef | undefined = candidate;
+  while (current) {
+    const parent = getAncestor(current);
+    if (parent === ancestor) {
+      return true;
+    }
+    current = parent;
+  }
+  return false;
+}

package/bundled-types/host-app/commands/create-submission-workflow.ts

@@ -0,0 +1,172 @@
+import { service } from '@ember/service';
+
+import { isCardInstance, rri, toBranchName } from '@cardstack/runtime-common';
+import type { LooseSingleCardDocument } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import UseAiAssistantCommand from './ai-assistant';
+import SendBotTriggerEventCommand from './bot-requests/send-bot-trigger-event';
+import OpenInInteractModeCommand from './open-in-interact-mode';
+
+import type MatrixService from '../services/matrix-service';
+import type RealmService from '../services/realm';
+import type RealmServerService from '../services/realm-server';
+import type StoreService from '../services/store';
+import type { Listing } from '@cardstack/catalog/catalog-app/listing/listing';
+
+export default class CreateSubmissionWorkflowCommand extends HostBaseCommand<
+  typeof BaseCommandModule.CreateListingPRRequestInput
+> {
+  @service declare private matrixService: MatrixService;
+  @service declare private store: StoreService;
+  @service declare private realm: RealmService;
+  @service declare private realmServer: RealmServerService;
+
+  description =
+    'Create a submission workflow card for a catalog listing, open it in interact mode, and trigger the PR creation process.';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { CreateListingPRRequestInput } = commandModule;
+    return CreateListingPRRequestInput;
+  }
+
+  requireInputFields = ['realm', 'listingId'];
+
+  get submissionsRealm(): string | undefined {
+    return this.realmServer.catalogRealmURLs.find((realm) =>
+      realm.endsWith('/submissions/'),
+    );
+  }
+
+  protected async run(
+    input: BaseCommandModule.CreateListingPRRequestInput,
+  ): Promise<undefined> {
+    await this.matrixService.ready;
+
+    let { realm, listingId } = input;
+    let listingName: string | undefined;
+    let listingSummary: string | undefined;
+    let listing = await this.store.get<Listing>(listingId);
+    if (listing && isCardInstance(listing)) {
+      listingName = listing.name ?? listing.id;
+      listingSummary = listing.summary ?? undefined;
+    }
+
+    let submittedBy = this.matrixService.userId ?? undefined;
+
+    // Save the workflow card in the user's realm (where the listing lives)
+    let workflowRealm = this.realm.realmOf(rri(listingId)) ?? realm;
+
+    let catalogRealm = this.catalogRealm;
+    if (!catalogRealm) {
+      throw new Error(
+        'Cannot create submission workflow: catalog realm URL not found',
+      );
+    }
+
+    // Create the Matrix room first so its id can be persisted on the workflow
+    // card — the retry flow reads roomId off the card to re-emit the bot
+    // trigger event without losing the original conversation.
+    let useAiAssistantCommand = new UseAiAssistantCommand(this.commandContext);
+    let createRoomResult = await useAiAssistantCommand.execute({
+      roomId: 'new',
+      roomName: `PR: ${listingName ?? listingId ?? 'Listing'}`,
+      openRoom: false,
+    });
+    let roomId = createRoomResult.roomId;
+
+    // Branch name is generated once and persisted on the workflow card so
+    // retries reuse the same GitHub branch.
+    let branchName = toBranchName(listingName ?? 'UntitledListing');
+
+    // Cleanup window covers everything between "room exists" and "workflow
+    // card persisted with roomId baked in". Once the card exists, leaving
+    // the room would orphan the card's roomId reference, so cleanup stops.
+    let workflowCardId: string;
+    try {
+      let submissionBotId = this.matrixService.submissionBotUserId;
+      if (!(await this.matrixService.isUserInRoom(roomId, submissionBotId))) {
+        await this.matrixService.inviteUserToRoom(roomId, submissionBotId);
+      }
+
+      let workflowDoc: LooseSingleCardDocument = {
+        data: {
+          type: 'card',
+          attributes: {
+            title: `Submit ${listingName ?? 'Listing'}`,
+            submittedBy: submittedBy ?? null,
+            catalogRealmUrl: catalogRealm,
+            roomId,
+            branchName,
+          },
+          relationships: {
+            listing: { links: { self: listingId } },
+            prCard: { links: { self: null } },
+          },
+          meta: {
+            adoptsFrom: {
+              module: rri(
+                `${catalogRealm}submission-workflow-card/submission-workflow-card`,
+              ),
+              name: 'SubmissionWorkflowCard',
+            },
+          },
+        },
+      };
+
+      let workflowCard = await this.store.add(workflowDoc, {
+        realm: workflowRealm,
+      });
+
+      if (!isCardInstance(workflowCard)) {
+        throw new Error('Failed to create submission workflow card');
+      }
+      if (!workflowCard.id) {
+        throw new Error('Submission workflow card was created but has no ID');
+      }
+      workflowCardId = workflowCard.id;
+    } catch (err) {
+      try {
+        await this.matrixService.leave(roomId);
+        await this.matrixService.forget(roomId);
+      } catch (cleanupError) {
+        console.warn(
+          `create-submission-workflow: failed to clean up orphaned room ${roomId}`,
+          cleanupError,
+        );
+      }
+      throw err;
+    }
+
+    await new OpenInInteractModeCommand(this.commandContext).execute({
+      cardId: workflowCardId,
+    });
+
+    await new SendBotTriggerEventCommand(this.commandContext).execute({
+      roomId,
+      realm,
+      type: 'pr-listing-create',
+      input: {
+        roomId,
+        realm,
+        listingId,
+        workflowCardUrl: workflowCardId,
+        workflowCardRealm: workflowRealm,
+        branchName,
+        ...(listingName ? { listingName } : {}),
+        ...(listingSummary ? { listingSummary } : {}),
+        ...(submittedBy ? { submittedBy } : {}),
+      },
+    });
+  }
+
+  private get catalogRealm(): string | undefined {
+    return this.realmServer.catalogRealmURLs.find((realm) =>
+      realm.endsWith('/catalog/'),
+    );
+  }
+}

package/bundled-types/host-app/commands/evaluate-module.ts

@@ -0,0 +1,119 @@
+/**
+ * Host command that evaluates a .gts module by importing it via the Loader.
+ * Runs in the prerenderer's headless Chrome — the sandbox for untrusted code.
+ *
+ * Uses `loader.import()` to load the module. If the module or any of its
+ * dependencies fail to load, the Loader throws (the module transitions to
+ * 'broken' state). This catches compile errors, runtime evaluation crashes,
+ * strict-mode template errors, and broken imports (when the import is consumed).
+ *
+ * Used by the software-factory's EvalValidationStep via `_run-command`.
+ */
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+export default class EvaluateModuleCommand extends HostBaseCommand<
+  typeof BaseCommandModule.EvaluateModuleInput,
+  typeof BaseCommandModule.EvaluateModuleResult
+> {
+  description = 'Evaluate a .gts module via the Loader in the prerenderer';
+  static actionVerb = 'Evaluate';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    return commandModule.EvaluateModuleInput;
+  }
+
+  requireInputFields = ['moduleIdentifier'];
+
+  protected async run(
+    input: BaseCommandModule.EvaluateModuleInput,
+  ): Promise<BaseCommandModule.EvaluateModuleResult> {
+    let moduleUrl = input.moduleIdentifier;
+    let realmUrl = input.realmIdentifier;
+
+    if (!moduleUrl) {
+      throw new Error('moduleUrl is required');
+    }
+
+    if (realmUrl) {
+      this.validateModuleUrl(moduleUrl, realmUrl);
+    }
+
+    let commandModule = await this.loadCommandModule();
+
+    try {
+      // Reset the loader to clear cached modules from prior eval runs.
+      // Without this, the Loader's internal module Map retains the old
+      // compiled bytecode and `loader.import()` returns the cached
+      // (stale) result — so edits the factory agent makes between
+      // validation turns are invisible to the eval step.
+      this.loaderService.resetLoader({
+        clearFetchCache: true,
+        reason: 'evaluate-module: fresh eval requires uncached loader',
+      });
+      let loader = this.loaderService.loader;
+      await loader.import(moduleUrl);
+
+      return new commandModule.EvaluateModuleResult({ passed: true });
+    } catch (error: any) {
+      let message = error?.message ?? String(error);
+      let stack = error?.stack;
+
+      return new commandModule.EvaluateModuleResult({
+        passed: false,
+        error: message,
+        stackTrace: stack,
+      });
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // URL validation helpers (SSRF prevention)
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Ensures moduleUrl is an http(s) URL that lives under the given realmUrl.
+   * Throws if validation fails.
+   */
+  private validateModuleUrl(moduleUrl: string, realmUrl: string): void {
+    this.assertHttpOrHttpsUrl(moduleUrl, 'moduleUrl');
+    this.assertHttpOrHttpsUrl(realmUrl, 'realmUrl');
+
+    let mod = new URL(moduleUrl);
+    let realm = new URL(realmUrl);
+
+    if (mod.origin !== realm.origin) {
+      throw new Error(
+        `moduleUrl origin (${mod.origin}) does not match realmUrl origin (${realm.origin})`,
+      );
+    }
+
+    let realmPath = this.normalizeRealmPathname(realm.pathname);
+    if (!mod.pathname.startsWith(realmPath)) {
+      throw new Error(
+        `moduleUrl path (${mod.pathname}) is not under realmUrl path (${realmPath})`,
+      );
+    }
+  }
+
+  private assertHttpOrHttpsUrl(value: string, label: string): void {
+    let url: URL;
+    try {
+      url = new URL(value);
+    } catch {
+      throw new Error(`${label} is not a valid URL: ${value}`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      throw new Error(
+        `${label} must use http or https scheme, got ${url.protocol}`,
+      );
+    }
+  }
+
+  private normalizeRealmPathname(pathname: string): string {
+    return pathname.endsWith('/') ? pathname : `${pathname}/`;
+  }
+}