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

package/bundled-types/host-app/commands/update-room-skills.ts

@@ -0,0 +1,231 @@
+import { service } from '@ember/service';
+
+import { isCardErrorJSONAPI, isCardInstance } from '@cardstack/runtime-common';
+import { APP_BOXEL_ROOM_SKILLS_EVENT_TYPE } from '@cardstack/runtime-common/matrix-constants';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+import type { SerializedFile } from 'https://cardstack.com/base/file-api';
+
+import type * as SkillModule from 'https://cardstack.com/base/skill';
+
+import { isSkillCard } from '../lib/file-def-manager';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import type MatrixService from '../services/matrix-service';
+import type StoreService from '../services/store';
+
+export default class UpdateRoomSkillsCommand extends HostBaseCommand<
+  typeof BaseCommandModule.UpdateRoomSkillsInput
+> {
+  @service declare private matrixService: MatrixService;
+  @service declare private store: StoreService;
+
+  static actionVerb = 'Update';
+  description = 'Updates the enabled and disabled skills for a room';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { UpdateRoomSkillsInput } = commandModule;
+    return UpdateRoomSkillsInput;
+  }
+
+  requireInputFields = ['roomId'];
+
+  protected async run(
+    input: BaseCommandModule.UpdateRoomSkillsInput,
+  ): Promise<undefined> {
+    let {
+      roomId,
+      skillCardIdsToActivate = [],
+      skillCardIdsToDeactivate = [],
+    } = input;
+
+    await this.matrixService.updateStateEvent(
+      roomId,
+      APP_BOXEL_ROOM_SKILLS_EVENT_TYPE,
+      '',
+      async (currentSkillsConfig: Record<string, any> = {}) => {
+        let enabledSkillCardMap = new Map<string, SerializedFile>();
+        let disabledSkillCardMap = new Map<string, SerializedFile>();
+
+        for (let fileDef of currentSkillsConfig.enabledSkillCards ?? []) {
+          if (fileDef?.sourceUrl) {
+            enabledSkillCardMap.set(fileDef.sourceUrl, fileDef);
+          }
+        }
+
+        for (let fileDef of currentSkillsConfig.disabledSkillCards ?? []) {
+          if (fileDef?.sourceUrl) {
+            disabledSkillCardMap.set(fileDef.sourceUrl, fileDef);
+          }
+        }
+
+        let skillIdsToDeactivate = new Set(skillCardIdsToDeactivate);
+        for (let skillId of skillIdsToDeactivate) {
+          if (enabledSkillCardMap.has(skillId)) {
+            let fileDef = enabledSkillCardMap.get(skillId)!;
+            enabledSkillCardMap.delete(skillId);
+            disabledSkillCardMap.set(skillId, fileDef);
+          }
+        }
+
+        let skillCardCache = new Map<string, SkillModule.Skill>();
+        let skillsNeedingUpload: SkillModule.Skill[] = [];
+        let skillIdsToActivate = new Set(skillCardIdsToActivate);
+
+        for (let skillId of skillIdsToActivate) {
+          if (enabledSkillCardMap.has(skillId)) {
+            continue;
+          }
+          if (disabledSkillCardMap.has(skillId)) {
+            let fileDef = disabledSkillCardMap.get(skillId)!;
+            disabledSkillCardMap.delete(skillId);
+            enabledSkillCardMap.set(skillId, fileDef);
+            continue;
+          }
+
+          try {
+            let maybeSkillCard =
+              await this.store.get<SkillModule.Skill>(skillId);
+            if (
+              isCardInstance(maybeSkillCard) &&
+              Object.prototype.hasOwnProperty.call(maybeSkillCard, isSkillCard)
+            ) {
+              let skillCard = maybeSkillCard as SkillModule.Skill;
+              skillCardCache.set(skillId, skillCard);
+              skillsNeedingUpload.push(skillCard);
+            } else {
+              console.warn(
+                `[UpdateRoomSkillsCommand] skipping activation of "${skillId}": ${describeStoreResult(maybeSkillCard)}`,
+              );
+            }
+          } catch (err) {
+            console.warn(
+              `[UpdateRoomSkillsCommand] skipping activation of "${skillId}": store.get threw: ${errorSummary(err)}`,
+            );
+          }
+        }
+
+        if (skillsNeedingUpload.length > 0) {
+          let uploadedSkillFileDefs = await this.matrixService.uploadCards(
+            skillsNeedingUpload as CardDef[],
+          );
+          for (let uploaded of uploadedSkillFileDefs) {
+            let serialized = uploaded.serialize();
+            if (serialized.sourceUrl) {
+              enabledSkillCardMap.set(serialized.sourceUrl, serialized);
+              disabledSkillCardMap.delete(serialized.sourceUrl);
+            }
+          }
+        }
+
+        // Ensure skills that ended up enabled are not left in the disabled map
+        for (let skillId of enabledSkillCardMap.keys()) {
+          disabledSkillCardMap.delete(skillId);
+        }
+
+        let enabledSkillIds = Array.from(enabledSkillCardMap.keys());
+        let loadedEnabledSkills = await Promise.all(
+          enabledSkillIds.map(async (skillId) => {
+            if (skillCardCache.has(skillId)) {
+              return skillCardCache.get(skillId)!;
+            }
+            try {
+              let maybeSkillCard =
+                await this.store.get<SkillModule.Skill>(skillId);
+              if (
+                isCardInstance(maybeSkillCard) &&
+                Object.prototype.hasOwnProperty.call(
+                  maybeSkillCard,
+                  isSkillCard,
+                )
+              ) {
+                let skillCard = maybeSkillCard as SkillModule.Skill;
+                skillCardCache.set(skillId, skillCard);
+                return skillCard;
+              }
+              console.warn(
+                `[UpdateRoomSkillsCommand] cannot rehydrate enabled skill "${skillId}": ${describeStoreResult(maybeSkillCard)}`,
+              );
+            } catch (err) {
+              console.warn(
+                `[UpdateRoomSkillsCommand] cannot rehydrate enabled skill "${skillId}": store.get threw: ${errorSummary(err)}`,
+              );
+            }
+            return undefined;
+          }),
+        );
+
+        let validEnabledSkills = loadedEnabledSkills.filter(
+          (skill): skill is SkillModule.Skill => Boolean(skill),
+        );
+
+        let previousCommandDefinitions =
+          (currentSkillsConfig.commandDefinitions ?? []) as SerializedFile[];
+        let serializedCommandDefinitions: SerializedFile[] = [
+          ...previousCommandDefinitions,
+        ];
+
+        if (validEnabledSkills.length > 0) {
+          let allCommandDefinitions = validEnabledSkills.flatMap(
+            (skill) => skill.commands ?? [],
+          );
+
+          if (allCommandDefinitions.length > 0) {
+            let uniqueCommandDefinitions =
+              this.matrixService.getUniqueCommandDefinitions(
+                allCommandDefinitions,
+              );
+            let uploadedCommandDefs =
+              await this.matrixService.uploadCommandDefinitions(
+                uniqueCommandDefinitions,
+              );
+            serializedCommandDefinitions = uploadedCommandDefs.map((fileDef) =>
+              fileDef.serialize(),
+            );
+          } else {
+            serializedCommandDefinitions = [];
+          }
+        } else if (enabledSkillIds.length === 0) {
+          serializedCommandDefinitions = [];
+        }
+
+        return {
+          ...currentSkillsConfig,
+          enabledSkillCards: Array.from(enabledSkillCardMap.values()),
+          disabledSkillCards: Array.from(disabledSkillCardMap.values()),
+          commandDefinitions: serializedCommandDefinitions,
+        };
+      },
+    );
+  }
+}
+
+// Stable, redaction-safe one-line summary of whatever `store.get` produced for
+// a skill. Avoids dumping the full instance / error payload (which can be
+// large and may carry user content) while still naming the failure mode.
+function describeStoreResult(result: unknown): string {
+  if (result == null) {
+    return `store.get returned ${result === null ? 'null' : 'undefined'}`;
+  }
+  if (isCardErrorJSONAPI(result)) {
+    let status = (result as { status?: number }).status;
+    let title = (result as { title?: string }).title;
+    return `store.get returned a CardErrorJSONAPI (status=${status ?? 'n/a'}, title=${JSON.stringify(title ?? '')})`;
+  }
+  if (isCardInstance(result)) {
+    return `store.get returned a card instance that is not a Skill (id=${
+      (result as { id?: string }).id ?? '<no id>'
+    })`;
+  }
+  return `store.get returned an unrecognized value of type ${typeof result}`;
+}
+
+function errorSummary(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message || err.name;
+  }
+  return typeof err === 'string' ? err : `<${typeof err}>`;
+}

package/bundled-types/host-app/commands/utils.ts

@@ -0,0 +1,178 @@
+import { getOwner } from '@ember/owner';
+
+import {
+  APP_BOXEL_COMMAND_REQUESTS_KEY,
+  APP_BOXEL_COMMAND_RESULT_EVENT_TYPE,
+  APP_BOXEL_COMMAND_RESULT_REL_TYPE,
+  decodeCommandRequest,
+  type CommandContext,
+  type CommandRequest,
+} from '@cardstack/runtime-common';
+
+import {
+  basicMappings,
+  generateJsonSchemaForCardType,
+  getPatchTool,
+} from '@cardstack/runtime-common/helpers/ai';
+
+import type { CardDef } from 'https://cardstack.com/base/card-api';
+import type * as CardAPI from 'https://cardstack.com/base/card-api';
+import type {
+  CardMessageEvent,
+  CommandResultEvent,
+  MatrixEvent,
+  RealmEventContent,
+  Tool,
+} from 'https://cardstack.com/base/matrix-event';
+
+import GetEventsFromRoomCommand from './get-events-from-room';
+
+import type LoaderService from '../services/loader-service';
+import type MessageService from '../services/message-service';
+
+export async function waitForMatrixEvent(
+  commandContext: CommandContext,
+  roomId: string,
+  callback: (matrixEvents: MatrixEvent[]) => boolean,
+  options: { timeoutMs?: number } = {},
+): Promise<void> {
+  let timeoutMs = options.timeoutMs ?? 1000 * 60 * 20; // default to 20 minutes
+  let getEventsFromRoomCommand = new GetEventsFromRoomCommand(commandContext);
+  let done = false;
+  let allMatrixEvents: MatrixEvent[] = [];
+  let lastEventId: string | undefined = undefined;
+  let startTime = Date.now();
+  while (!done) {
+    // if there are no new events since the provided eventId, this command blocks until a new event appears or a timeout is reached
+    let result = await getEventsFromRoomCommand.execute({
+      roomId,
+      sinceEventId: lastEventId,
+    });
+    let matrixEvents = result.matrixEvents as MatrixEvent[];
+    allMatrixEvents = allMatrixEvents.concat(matrixEvents);
+
+    if (callback(allMatrixEvents)) {
+      done = true;
+    } else {
+      lastEventId = matrixEvents[matrixEvents.length - 1]?.event_id;
+    }
+    if (Date.now() - startTime > timeoutMs) {
+      throw new Error(`Timed out waiting for events in room ${roomId}`);
+    }
+  }
+}
+
+export async function waitForCompletedCommandRequest(
+  commandContext: CommandContext,
+  roomId: string,
+  commandRequestPredicate: (commandRequest: Partial<CommandRequest>) => boolean,
+  options: { timeoutMs?: number; afterEventId?: string } = {},
+): Promise<CommandResultEvent | undefined> {
+  let result: CommandResultEvent | undefined = undefined;
+  await waitForMatrixEvent(
+    commandContext,
+    roomId,
+    (matrixEvents: MatrixEvent[]) => {
+      let events = options.afterEventId
+        ? matrixEvents.slice(
+            matrixEvents.findIndex((e) => e.event_id === options.afterEventId) +
+              1,
+          )
+        : matrixEvents;
+      let commandResultEvents = events.filter(
+        (e) =>
+          e.type === APP_BOXEL_COMMAND_RESULT_EVENT_TYPE &&
+          e.content['m.relates_to']?.rel_type ===
+            APP_BOXEL_COMMAND_RESULT_REL_TYPE &&
+          e.content['m.relates_to']?.key === 'applied',
+      ) as CommandResultEvent[];
+      return commandResultEvents.some((commandResultEvent) => {
+        let eventWithRequest = events.find(
+          (e) =>
+            e.event_id === commandResultEvent.content['m.relates_to']?.event_id,
+        ) as CardMessageEvent | undefined;
+        if (!eventWithRequest) {
+          return false;
+        }
+        let commandRequests =
+          eventWithRequest.content[APP_BOXEL_COMMAND_REQUESTS_KEY] ?? [];
+        let commandRequest = commandRequests.find(
+          (commandRequest) =>
+            commandRequest.id === commandResultEvent.content.commandRequestId,
+        );
+        if (
+          commandRequest &&
+          commandRequestPredicate(decodeCommandRequest(commandRequest))
+        ) {
+          result = commandResultEvent;
+          return true;
+        }
+        return false;
+      });
+    },
+    { timeoutMs: options.timeoutMs },
+  );
+  return result;
+}
+
+export async function addPatchTools(
+  commandContext: CommandContext,
+  patchableCards: CardDef[],
+  cardAPI: typeof CardAPI,
+): Promise<Tool[]> {
+  let results: Tool[] = [];
+  let loader = (
+    getOwner(commandContext)!.lookup('service:loader-service') as LoaderService
+  ).loader;
+  let mappings = await basicMappings(loader);
+  for (const patchableCard of patchableCards) {
+    let patchSpec = generateJsonSchemaForCardType(
+      patchableCard.constructor as typeof CardDef,
+      cardAPI,
+      mappings,
+    );
+    results.push(getPatchTool(patchableCard.id, patchSpec));
+  }
+  return results;
+}
+
+export async function waitForRealmState(
+  commandContext: CommandContext,
+  realmId: string,
+  predicate: (ev: RealmEventContent | undefined) => boolean,
+  options: { timeoutMs?: number; keepRealmSubscription?: boolean } = {},
+): Promise<void> {
+  let timeoutMs = options.timeoutMs ?? 1000 * 60 * 20; // default to 20 minutes
+  let keepRealmSubscription = options.keepRealmSubscription ?? false;
+  if (predicate(undefined)) {
+    return;
+  }
+  const timeoutPromise = new Promise<void>((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`Timed out waiting for realm state in ${realmId}`));
+    }, timeoutMs);
+  });
+
+  const messageService = getOwner(commandContext)?.lookup(
+    'service:message-service',
+  ) as MessageService | undefined;
+  if (!messageService) {
+    throw new Error('MessageService not found');
+  }
+  let unsubscribe: () => void = () => {};
+  const predicateSucceededPromise = new Promise<void>((resolve) => {
+    unsubscribe = messageService.subscribe(realmId, (ev) => {
+      if (predicate(ev)) {
+        if (!keepRealmSubscription) {
+          unsubscribe?.();
+        }
+        resolve();
+      }
+    });
+  });
+  return Promise.race([predicateSucceededPromise, timeoutPromise]).finally(
+    () => {
+      unsubscribe?.();
+    },
+  );
+}

package/bundled-types/host-app/commands/validate-realm.ts

@@ -0,0 +1,40 @@
+import { RealmPaths } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+
+import GetAvailableRealmIdentifiersCommand from './get-available-realm-identifiers';
+
+export default class ValidateRealmCommand extends HostBaseCommand<
+  typeof BaseCommandModule.ValidateRealmInput,
+  typeof BaseCommandModule.ValidateRealmResult
+> {
+  description = 'Validate that a realm URL is available and normalize it';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { ValidateRealmInput } = commandModule;
+    return ValidateRealmInput;
+  }
+
+  requireInputFields = ['realmIdentifier'];
+
+  protected async run(
+    input: BaseCommandModule.ValidateRealmInput,
+  ): Promise<BaseCommandModule.ValidateRealmResult> {
+    let realmIdentifier = new RealmPaths(new URL(input.realmIdentifier)).url;
+
+    let { realmIdentifiers } = await new GetAvailableRealmIdentifiersCommand(
+      this.commandContext,
+    ).execute();
+
+    if (!realmIdentifiers.includes(realmIdentifier)) {
+      throw new Error(`Invalid realm: ${realmIdentifier}`);
+    }
+
+    let commandModule = await this.loadCommandModule();
+    const { ValidateRealmResult } = commandModule;
+    return new ValidateRealmResult({ realmIdentifier });
+  }
+}

package/bundled-types/host-app/commands/write-binary-file.ts

@@ -0,0 +1,142 @@
+import { service } from '@ember/service';
+
+import { v4 as uuidv4 } from 'uuid';
+
+import { rri } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+import { findNonConflictingFilename } from '../utils/file-name';
+
+import type CardService from '../services/card-service';
+import type NetworkService from '../services/network';
+import type RealmService from '../services/realm';
+
+function base64ToUint8Array(base64: string): Uint8Array {
+  const maybeBuffer = (globalThis as any).Buffer as
+    | { from(input: string, encoding: string): Buffer }
+    | undefined;
+
+  if (typeof maybeBuffer !== 'undefined') {
+    return new Uint8Array(maybeBuffer.from(base64, 'base64'));
+  }
+
+  if (typeof atob === 'function') {
+    const binaryString = atob(base64);
+    const bytes = new Uint8Array(binaryString.length);
+    for (let i = 0; i < binaryString.length; i++) {
+      bytes[i] = binaryString.charCodeAt(i);
+    }
+    return bytes;
+  }
+
+  throw new Error('No base64 decoder available in this environment');
+}
+
+export default class WriteBinaryFileCommand extends HostBaseCommand<
+  typeof BaseCommandModule.WriteBinaryFileInput,
+  typeof BaseCommandModule.WriteBinaryFileResult
+> {
+  @service declare private cardService: CardService;
+  @service declare private realm: RealmService;
+  @service declare private network: NetworkService;
+
+  description = 'Write a binary file to a realm';
+  static actionVerb = 'Write';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { WriteBinaryFileInput } = commandModule;
+    return WriteBinaryFileInput;
+  }
+
+  requireInputFields = ['path', 'base64Content'];
+
+  protected async run(
+    input: BaseCommandModule.WriteBinaryFileInput,
+  ): Promise<BaseCommandModule.WriteBinaryFileResult> {
+    let realm;
+    if (input.realm) {
+      realm = this.realm.realmOf(rri(input.realm));
+      if (!realm) {
+        throw new Error(`Invalid or unknown realm provided: ${input.realm}`);
+      }
+    }
+
+    let path = input.path;
+    if (path.startsWith('/')) {
+      path = path.slice(1);
+    }
+
+    let url = new URL(path, realm);
+    let finalUrl = url;
+
+    if (input.useNonConflictingFilename) {
+      let existing = await this.cardService.getSource(url);
+      if (existing.status === 200 || existing.status === 406) {
+        let nonConflictingUrl = await findNonConflictingFilename(
+          url.href,
+          (candidateUrl) => this.fileExists(candidateUrl),
+        );
+        finalUrl = new URL(nonConflictingUrl);
+      } else if (existing.status !== 404) {
+        throw new Error(
+          `Error checking if file exists at ${url}: ${existing.status}`,
+        );
+      }
+    }
+
+    let bytes = base64ToUint8Array(input.base64Content);
+    let blob = new Blob([bytes as any]);
+
+    let clientRequestId = `binary:${uuidv4()}`;
+    this.cardService.clientRequestIds.add(clientRequestId);
+
+    let response = await this.network.authedFetch(finalUrl, {
+      method: 'POST',
+      headers: {
+        // Realm router matches binary uploads by application/octet-stream
+        'Content-Type': 'application/octet-stream',
+        'X-Boxel-Client-Request-Id': clientRequestId,
+      },
+      body: blob,
+    });
+
+    if (!response.ok) {
+      const MAX_RESPONSE_TEXT_LENGTH = 500;
+      let responseText: string;
+      try {
+        let rawText = await response.text();
+        responseText =
+          rawText.length > MAX_RESPONSE_TEXT_LENGTH
+            ? rawText.slice(0, MAX_RESPONSE_TEXT_LENGTH) +
+              `… (${rawText.length} chars total)`
+            : rawText;
+      } catch {
+        responseText = '(unable to read response body)';
+      }
+      let wafRule = response.headers.get('x-blocked-by-waf-rule');
+      let details = [
+        `[WriteBinaryFile] Failed to write ${finalUrl}`,
+        `Status: ${response.status} ${response.statusText}`,
+        `File size: ${bytes.byteLength} bytes`,
+        wafRule ? `WAF rule: ${wafRule}` : null,
+        `Response: ${responseText}`,
+      ]
+        .filter(Boolean)
+        .join(' | ');
+      console.error(details);
+      throw new Error(details);
+    }
+
+    let commandModule = await this.loadCommandModule();
+    const { WriteBinaryFileResult } = commandModule;
+    return new WriteBinaryFileResult({ fileIdentifier: finalUrl.href });
+  }
+
+  private async fileExists(fileUrl: string): Promise<boolean> {
+    let getSourceResult = await this.cardService.getSource(rri(fileUrl));
+    return getSourceResult.status !== 404;
+  }
+}

package/bundled-types/host-app/commands/write-text-file.ts

@@ -0,0 +1,104 @@
+import { service } from '@ember/service';
+
+import { rri } from '@cardstack/runtime-common';
+
+import type * as BaseCommandModule from 'https://cardstack.com/base/command';
+
+import HostBaseCommand from '../lib/host-base-command';
+import { findNonConflictingFilename } from '../utils/file-name';
+
+import type CardService from '../services/card-service';
+import type { SaveType } from '../services/card-service';
+import type RealmService from '../services/realm';
+
+export default class WriteTextFileCommand extends HostBaseCommand<
+  typeof BaseCommandModule.WriteTextFileInput,
+  typeof BaseCommandModule.FileIdentifierCard
+> {
+  @service declare private cardService: CardService;
+  @service declare private realm: RealmService;
+
+  description = `Write a text file to a realm, such as a module or a card.`;
+  static actionVerb = 'Write';
+
+  async getInputType() {
+    let commandModule = await this.loadCommandModule();
+    const { WriteTextFileInput } = commandModule;
+    return WriteTextFileInput;
+  }
+
+  requireInputFields = ['path', 'content'];
+
+  protected async run(
+    input: BaseCommandModule.WriteTextFileInput,
+  ): Promise<BaseCommandModule.FileIdentifierCard> {
+    if (input.overwrite && input.useNonConflictingFilename) {
+      throw new Error(
+        'Cannot use both overwrite and useNonConflictingFilename.',
+      );
+    }
+    let realm;
+    if (input.realm) {
+      realm = this.realm.realmOf(rri(input.realm));
+      if (!realm) {
+        throw new Error(`Invalid or unknown realm provided: ${input.realm}`);
+      }
+    }
+    let path = input.path;
+    if (path.startsWith('/')) {
+      path = path.slice(1);
+    }
+    let url = new URL(path, realm);
+    let finalUrl = url;
+    let shouldWrite = true;
+    if (!input.overwrite) {
+      if (input.useNonConflictingFilename) {
+        let existing = await this.cardService.getSource(url);
+        if (existing.status === 404) {
+          shouldWrite = true;
+        } else if (existing.status === 200) {
+          if (existing.content.trim() !== '') {
+            let nonConflictingUrl = await findNonConflictingFilename(
+              url.href,
+              (candidateUrl) => this.fileExists(candidateUrl),
+            );
+            finalUrl = new URL(nonConflictingUrl);
+          } else {
+            shouldWrite = input.content.trim() !== '';
+          }
+        } else {
+          throw new Error(
+            `Error checking if file exists at ${url}: ${existing.status}`,
+          );
+        }
+      } else {
+        let existing = await this.cardService.getSource(url);
+        if (existing.status === 200 || existing.status === 406) {
+          throw new Error(`File already exists: ${path}`);
+        }
+
+        if (existing.status !== 404) {
+          let errorDetails = existing.content?.trim()
+            ? `${existing.content} (${existing.status})`
+            : `${existing.status}`;
+          throw new Error(
+            `Error checking if file exists at ${path}: ${errorDetails}`,
+          );
+        }
+      }
+    }
+    if (shouldWrite) {
+      let saveType: SaveType = input.overwrite ? 'editor' : 'create-file';
+      await this.cardService.saveSource(finalUrl, input.content, saveType);
+    }
+
+    let commandModule = await this.loadCommandModule();
+    const { FileIdentifierCard } = commandModule;
+    return new FileIdentifierCard({ fileIdentifier: finalUrl.href });
+  }
+
+  private async fileExists(fileUrl: string): Promise<boolean> {
+    let getSourceResult = await this.cardService.getSource(rri(fileUrl));
+    return getSourceResult.status !== 404;
+  }
+}