Add @cardstack/skills universal reference (#4206)

backspace · web-flow · commit 3ab3d2cd9d35 · 2026-03-30T09:48:03.000-05:00
diff --git a/mise-tasks/services/realm-server b/mise-tasks/services/realm-server
@@ -102,7 +102,7 @@ LOW_CREDIT_THRESHOLD="${LOW_CREDIT_THRESHOLD:-2000}" \
   \
   --path='../skills-realm/contents' \
   --username='skills_realm' \
-  --fromUrl="${REALM_BASE_URL}/skills/" \
+  --fromUrl='@cardstack/skills/' \
   --toUrl="${REALM_BASE_URL}/skills/" \
   \
   ${START_SUBMISSION:+--path="${SUBMISSION_REALM_PATH}"} \
diff --git a/mise-tasks/services/worker b/mise-tasks/services/worker
@@ -40,7 +40,7 @@ NODE_ENV=development \
   ${START_CATALOG:+--fromUrl='@cardstack/catalog/'} \
   ${START_CATALOG:+--toUrl="${CATALOG_REALM_URL}"} \
   \
-  --fromUrl="${REALM_BASE_URL}/skills/" \
+  --fromUrl='@cardstack/skills/' \
   --toUrl="${REALM_BASE_URL}/skills/" \
   \
   ${START_CATALOG:+--fromUrl="${EXTERNAL_CATALOG_REALM_URL}"} \
diff --git a/mise-tasks/services/worker-test b/mise-tasks/services/worker-test
@@ -38,5 +38,5 @@ NODE_ENV=test \
   --toUrl="${REALM_TEST_URL}/test/" \
   --fromUrl='https://cardstack.com/base/' \
   --toUrl="${REALM_BASE_URL}/base/" \
-  --fromUrl="${REALM_BASE_URL}/skills/" \
+  --fromUrl='@cardstack/skills/' \
   --toUrl="${REALM_BASE_URL}/skills/"
diff --git a/packages/base/card-api.gts b/packages/base/card-api.gts
@@ -2832,7 +2832,7 @@ function lazilyLoadLink(
         fieldValue = (await createFromSerialized(
           fileMetaDoc.data,
           fileMetaDoc,
-          new URL(fileMetaDoc.data.id!),
+          cardIdToURL(fileMetaDoc.data.id!),
           { store, dependencyTrackingContext },
         )) as FileDef;
       } else {
@@ -2848,7 +2848,7 @@ function lazilyLoadLink(
         fieldValue = (await createFromSerialized(
           cardDoc.data,
           cardDoc,
-          new URL(cardDoc.data.id!),
+          cardIdToURL(cardDoc.data.id!),
           { store, dependencyTrackingContext },
         )) as CardDef;
       }
@@ -3173,7 +3173,7 @@ export async function updateFromSerialized<T extends BaseDefConstructor>(
 ): Promise<BaseInstanceType<T>> {
   stores.set(instance, store);
   if (!instance[relativeTo] && doc.data.id) {
-    instance[relativeTo] = new URL(doc.data.id);
+    instance[relativeTo] = cardIdToURL(doc.data.id);
   }
 
   if (isCardInstance(instance)) {
@@ -3299,7 +3299,7 @@ async function _updateFromSerialized<T extends BaseDefConstructor>({
   let instanceRelativeTo =
     instance[relativeTo] ??
     ('id' in instance && typeof instance.id === 'string'
-      ? new URL(instance.id)
+      ? cardIdToURL(instance.id)
       : undefined);
 
   function getFieldMeta(
@@ -3482,7 +3482,7 @@ async function _updateFromSerialized<T extends BaseDefConstructor>({
       let relativeToVal =
         instance[relativeTo] ??
         ('id' in instance && typeof instance.id === 'string'
-          ? new URL(instance.id)
+          ? cardIdToURL(instance.id)
           : undefined);
       let deserializedValue = await getDeserializedValue({
         card,
diff --git a/packages/base/cards-grid.gts b/packages/base/cards-grid.gts
@@ -14,6 +14,7 @@ import Captions from '@cardstack/boxel-icons/captions';
 import AllCardsIcon from '@cardstack/boxel-icons/square-stack';
 
 import {
+  cardIdToURL,
   chooseCard,
   specRef,
   baseRealm,
@@ -258,7 +259,7 @@ class Isolated extends Component<typeof CardsGrid> {
     }
 
     if (spec && isCardInstance<Spec>(spec)) {
-      await this.args.createCard?.(spec.ref, new URL(spec.id!), {
+      await this.args.createCard?.(spec.ref, cardIdToURL(spec.id!), {
         realmURL: this.args.model[realmURL],
       });
     }
diff --git a/packages/base/query-field-support.ts b/packages/base/query-field-support.ts
@@ -13,6 +13,7 @@ import type {
   RuntimeDependencyTrackingContext,
 } from '@cardstack/runtime-common';
 import {
+  cardIdToURL,
   getField,
   getSingularRelationship,
   identifyCard,
@@ -361,7 +362,7 @@ function resolveQueryAndRealm(
     fieldPath,
     resolvePathValue: (path) => resolveInstancePathValue(instance, path),
     relativeTo: (instance as CardDef).id
-      ? new URL((instance as CardDef).id)
+      ? cardIdToURL((instance as CardDef).id)
       : realmURL,
   });
 
diff --git a/packages/host/app/components/operator-mode/submode-layout.gts b/packages/host/app/components/operator-mode/submode-layout.gts
@@ -24,6 +24,7 @@ import { bool, cn, not } from '@cardstack/boxel-ui/helpers';
 
 import { BoxelIconWithText } from '@cardstack/boxel-ui/icons';
 
+import { cardIdToURL } from '@cardstack/runtime-common';
 import type { ResolvedCodeRef } from '@cardstack/runtime-common';
 
 import AiAssistantButton from '@cardstack/host/components/ai-assistant/button';
@@ -182,7 +183,7 @@ export default class SubmodeLayout extends Component<Signature> {
       case Submodes.Code:
         await this.operatorModeStateService.updateCodePath(
           this.lastCardIdInRightMostStack
-            ? new URL(this.lastCardIdInRightMostStack + '.json')
+            ? cardIdToURL(this.lastCardIdInRightMostStack + '.json')
             : null,
         );
         break;
diff --git a/packages/host/app/lib/realm-utils.ts b/packages/host/app/lib/realm-utils.ts
@@ -1,4 +1,4 @@
-import { RealmPaths } from '@cardstack/runtime-common';
+import { cardIdToURL, RealmPaths } from '@cardstack/runtime-common';
 
 /**
  * Normalizes realm URLs by ensuring they have trailing slashes and
@@ -33,7 +33,7 @@ export function normalizeRealms(realms: string[]): string[] {
  * // Returns: 'http://localhost:4201/test/'
  */
 export function resolveCardRealmUrl(cardId: string, realms: string[]): string {
-  let cardUrl = new URL(cardId);
+  let cardUrl = cardIdToURL(cardId);
   for (let realm of realms) {
     let realmUrl = new URL(realm);
     let realmPaths = new RealmPaths(realmUrl);
diff --git a/packages/host/app/lib/utils.ts b/packages/host/app/lib/utils.ts
@@ -68,18 +68,17 @@ export const catalogRealm = ENV.resolvedCatalogRealmURL
 export const skillsRealm = new RealmPaths(new URL(ENV.resolvedSkillsRealmURL));
 
 /**
- * Safely constructs a URL to a skill card in the skills realm.
- * Uses the URL constructor to handle path joining safely.
+ * Constructs a universal @cardstack/skills/ reference to a skill card.
  *
  * @param skillId - The ID of the skill (e.g., 'boxel-environment', 'catalog-listing')
- * @returns The complete URL to the skill card
+ * @returns The universal skill card reference
  *
  * @example
- * skillCardURL('catalog-listing')   // 'http://localhost:4201/skills/Skill/catalog-listing'
+ * skillCardURL('catalog-listing')   // '@cardstack/skills/Skill/catalog-listing'
  */
 export function skillCardURL(skillId: string): string {
-  return skillsRealm.fileURL(`Skill/${skillId}`).href;
+  return `@cardstack/skills/Skill/${skillId}`;
 }
 
-export const devSkillId = skillsRealm.fileURL(devSkillLocalPath).href;
-export const envSkillId = skillsRealm.fileURL(envSkillLocalPath).href;
+export const devSkillId = `@cardstack/skills/${devSkillLocalPath}`;
+export const envSkillId = `@cardstack/skills/${envSkillLocalPath}`;
diff --git a/packages/host/app/resources/room.ts b/packages/host/app/resources/room.ts
@@ -11,6 +11,7 @@ import difference from 'lodash/difference';
 import { TrackedMap } from 'tracked-built-ins';
 
 import {
+  cardIdToURL,
   isCardInstance,
   type LooseSingleCardDocument,
 } from '@cardstack/runtime-common';
@@ -317,7 +318,7 @@ export class RoomResource extends Resource<Args> {
     for (let skillCard of this.allSkillFileDefs) {
       result.push({
         cardId: skillCard.sourceUrl,
-        realmURL: this.realm.realmOfURL(new URL(skillCard.sourceUrl))?.href,
+        realmURL: this.realm.realmOfURL(cardIdToURL(skillCard.sourceUrl))?.href,
         fileDef: skillCard,
         isActive:
           this.matrixRoom?.skillsConfig.enabledSkillCards
diff --git a/packages/host/app/routes/render.ts b/packages/host/app/routes/render.ts
@@ -298,7 +298,7 @@ export default class RenderRoute extends Route<Model> {
       let instance = (await this.store.addFileMeta(
         resource,
         doc,
-        resource.id ? new URL(resource.id) : undefined,
+        resource.id ? cardIdToURL(resource.id) : undefined,
       )) as unknown as CardDef;
 
       let state = new TrackedMap<string, unknown>();
diff --git a/packages/host/app/services/network.ts b/packages/host/app/services/network.ts
@@ -67,6 +67,14 @@ export default class NetworkService extends Service {
         (rest) => new URL(rest, catalogURL).href,
       );
     }
+    if (config.resolvedSkillsRealmURL) {
+      let skillsURL = withTrailingSlash(config.resolvedSkillsRealmURL);
+      registerCardReferencePrefix('@cardstack/skills/', skillsURL);
+      virtualNetwork.addImportMap(
+        '@cardstack/skills/',
+        (rest) => new URL(rest, skillsURL).href,
+      );
+    }
     if (config.resolvedOpenRouterRealmURL) {
       let openRouterURL = withTrailingSlash(config.resolvedOpenRouterRealmURL);
       registerCardReferencePrefix('@cardstack/openrouter/', openRouterURL);
diff --git a/packages/host/app/services/operator-mode-state-service.ts b/packages/host/app/services/operator-mode-state-service.ts
@@ -13,9 +13,9 @@ import { TrackedArray, TrackedMap, TrackedObject } from 'tracked-built-ins';
 
 import type { CodeRef } from '@cardstack/runtime-common';
 import {
+  cardIdToURL,
   RealmPaths,
   type LocalPath,
-  cardIdToURL,
   isResolvedCodeRef,
   isCardInstance,
   isLocalId,
@@ -344,7 +344,7 @@ export default class OperatorModeStateService extends Service {
       this.trimItemsFromStack(item);
     }
     let realmPaths = new RealmPaths(new URL(cardRealmUrl));
-    let cardPath = realmPaths.local(new URL(`${cardId}.json`));
+    let cardPath = realmPaths.local(cardIdToURL(`${cardId}.json`));
     this.recentFilesService.removeRecentFile(cardPath);
     this.recentCardsService.remove(cardId);
   }
diff --git a/packages/host/app/services/realm.ts b/packages/host/app/services/realm.ts
@@ -30,6 +30,8 @@ import type {
 import {
   Deferred,
   ensureTrailingSlash,
+  isRegisteredPrefix,
+  cardIdToURL,
   logger,
   SupportedMimeType,
   type RealmInfo,
@@ -795,6 +797,9 @@ export default class RealmService extends Service {
   }
 
   info = (url: string): EnhancedRealmInfo => {
+    if (isRegisteredPrefix(url)) {
+      url = cardIdToURL(url).href;
+    }
     let resource = this.knownRealm(url, { tracked: false });
     if (!resource) {
       this.identifyRealm.perform(url);
@@ -837,6 +842,9 @@ export default class RealmService extends Service {
   };
 
   async allUsersPermissions(url: string) {
+    if (isRegisteredPrefix(url)) {
+      url = cardIdToURL(url).href;
+    }
     let resource = this.knownRealm(url);
     if (!resource) {
       await this.identifyRealm.perform(url);
diff --git a/packages/host/app/services/store.ts b/packages/host/app/services/store.ts
@@ -19,6 +19,7 @@ import {
   baseFileRef,
   CardError,
   cardIdToURL,
+  isRegisteredPrefix,
   hasExecutableExtension,
   isCardError,
   isCardInstance,
@@ -1326,7 +1327,7 @@ export default class StoreService extends Service implements StoreInterface {
       return this.createFileMetaFromSerialized(
         resource,
         doc,
-        new URL(resource.id),
+        cardIdToURL(resource.id),
         dependencyTrackingContext,
       ) as Promise<T>;
     }
@@ -1430,7 +1431,7 @@ export default class StoreService extends Service implements StoreInterface {
         deferred?.fulfill(existingInstance as T | CardErrorJSONAPI);
         return existingInstance as T;
       }
-      if (isLocalId(id)) {
+      if (isLocalId(id) && !isRegisteredPrefix(id)) {
         // we might have lost the local id via a loader refresh, try loading from remote id instead
         let remoteId = this.store.getRemoteIds(id)?.[0];
         if (!remoteId) {
@@ -1440,7 +1441,9 @@ export default class StoreService extends Service implements StoreInterface {
         }
         id = remoteId;
       }
-      let url = id; // after this point we know we are dealing with a remote id, e.g. url
+      // Resolve registered prefix IDs (e.g. @cardstack/skills/...) to actual
+      // URLs so they can be used for fetching.
+      let url = isRegisteredPrefix(id) ? cardIdToURL(id).href : id;
       let doc = (typeof idOrDoc !== 'string' ? idOrDoc : undefined) as
         | SingleCardDocument
         | undefined;
@@ -1560,10 +1563,10 @@ export default class StoreService extends Service implements StoreInterface {
         deferred.fulfill(existingInstance as T | CardErrorJSONAPI);
         return existingInstance as T | CardErrorJSONAPI;
       }
-      if (isLocalId(id)) {
+      if (isLocalId(id) && !isRegisteredPrefix(id)) {
         throw new Error(`file-meta reads do not support local ids (${id})`);
       }
-      let url = id;
+      let url = isRegisteredPrefix(id) ? cardIdToURL(id).href : id;
       let fileMetaDoc: SingleFileMetaDocument | CardError;
       if (this.isRenderStore && (globalThis as any).__boxelRenderContext) {
         fileMetaDoc = await this.extractFileMetaDirectly(url);
@@ -1579,7 +1582,7 @@ export default class StoreService extends Service implements StoreInterface {
       let fileInstance = await api.createFromSerialized(
         fileMetaDoc.data,
         fileMetaDoc,
-        fileMetaDoc.data.id ? new URL(fileMetaDoc.data.id) : new URL(url),
+        fileMetaDoc.data.id ? cardIdToURL(fileMetaDoc.data.id) : new URL(url),
         {
           store: this.store,
           dependencyTrackingContext: opts?.dependencyTrackingContext,
diff --git a/packages/host/tests/integration/components/ai-assistant-panel/skills-test.gts b/packages/host/tests/integration/components/ai-assistant-panel/skills-test.gts
diff --git a/packages/matrix/helpers/isolated-realm-server.ts b/packages/matrix/helpers/isolated-realm-server.ts
diff --git a/packages/matrix/tests/skills.spec.ts b/packages/matrix/tests/skills.spec.ts
diff --git a/packages/realm-server/scripts/start-production.sh b/packages/realm-server/scripts/start-production.sh
diff --git a/packages/realm-server/scripts/start-staging.sh b/packages/realm-server/scripts/start-staging.sh
diff --git a/packages/realm-server/scripts/start-worker-production.sh b/packages/realm-server/scripts/start-worker-production.sh
diff --git a/packages/realm-server/scripts/start-worker-staging.sh b/packages/realm-server/scripts/start-worker-staging.sh

Original file line number	Diff line number	Diff line change
`@@ -102,7 +102,7 @@ LOW_CREDIT_THRESHOLD="${LOW_CREDIT_THRESHOLD:-2000}" \`
`102`	`102`	`\`
`103`	`103`	`--path='../skills-realm/contents' \`
`104`	`104`	`--username='skills_realm' \`
`105`		`- --fromUrl="${REALM_BASE_URL}/skills/" \`
	`105`	`+ --fromUrl='@cardstack/skills/' \`
`106`	`106`	`--toUrl="${REALM_BASE_URL}/skills/" \`
`107`	`107`	`\`
`108`	`108`	`${START_SUBMISSION:+--path="${SUBMISSION_REALM_PATH}"} \`
Original file line number	Diff line number	Diff line change
`@@ -40,7 +40,7 @@ NODE_ENV=development \`
`40`	`40`	`${START_CATALOG:+--fromUrl='@cardstack/catalog/'} \`
`41`	`41`	`${START_CATALOG:+--toUrl="${CATALOG_REALM_URL}"} \`
`42`	`42`	`\`
`43`		`- --fromUrl="${REALM_BASE_URL}/skills/" \`
	`43`	`+ --fromUrl='@cardstack/skills/' \`
`44`	`44`	`--toUrl="${REALM_BASE_URL}/skills/" \`
`45`	`45`	`\`
`46`	`46`	`${START_CATALOG:+--fromUrl="${EXTERNAL_CATALOG_REALM_URL}"} \`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ import Captions from '@cardstack/boxel-icons/captions';`
`14`	`14`	`import AllCardsIcon from '@cardstack/boxel-icons/square-stack';`
`15`	`15`
`16`	`16`	`import {`
	`17`	`+ cardIdToURL,`
`17`	`18`	`chooseCard,`
`18`	`19`	`specRef,`
`19`	`20`	`baseRealm,`
`@@ -258,7 +259,7 @@ class Isolated extends Component<typeof CardsGrid> {`
`258`	`259`	`}`
`259`	`260`
`260`	`261`	`if (spec && isCardInstance<Spec>(spec)) {`
`261`		`- await this.args.createCard?.(spec.ref, new URL(spec.id!), {`
	`262`	`+ await this.args.createCard?.(spec.ref, cardIdToURL(spec.id!), {`
`262`	`263`	`realmURL: this.args.model[realmURL],`
`263`	`264`	`});`
`264`	`265`	`}`