@pi-stef/catalog 0.2.2

package/src/config/io.ts

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import yaml from "js-yaml";
+
+import { catalogFile, lockFile, ensureCatalogDir } from "./paths.js";
+import { CatalogYamlSchema, LockFileSchema } from "./schema.js";
+import type { CatalogYaml, LockFile } from "./schema.js";
+
+// ---------------------------------------------------------------------------
+// Empty defaults
+// ---------------------------------------------------------------------------
+
+const EMPTY_CATALOG: CatalogYaml = {
+  meta: { pi_version: "0.0.0" },
+  packages: {},
+};
+
+const EMPTY_LOCK: LockFile = { packages: {} };
+
+// ---------------------------------------------------------------------------
+// cat.yaml I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and parse `cat.yaml`. Returns an empty catalog when the file is
+ * missing or empty. Throws on malformed YAML or schema-invalid content.
+ */
+export function readCatalog(home?: string): CatalogYaml {
+  const filePath = catalogFile(home);
+
+  if (!fs.existsSync(filePath)) {
+    return structuredClone(EMPTY_CATALOG);
+  }
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+  if (raw.trim() === "") {
+    return structuredClone(EMPTY_CATALOG);
+  }
+
+  const parsed = yaml.load(raw);
+  return CatalogYamlSchema.parse(parsed);
+}
+
+/**
+ * Serialize and write `cat.yaml`, creating the catalog directory if needed.
+ */
+export function writeCatalog(catalog: CatalogYaml, home?: string): void {
+  ensureCatalogDir(home);
+  const filePath = catalogFile(home);
+  const content = yaml.dump(catalog);
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// catalog.lock.json I/O
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and parse `catalog.lock.json`. Returns an empty lock when the file
+ * is missing. Throws on malformed JSON or schema-invalid content.
+ */
+export function readLock(home?: string): LockFile {
+  const filePath = lockFile(home);
+
+  if (!fs.existsSync(filePath)) {
+    return structuredClone(EMPTY_LOCK);
+  }
+
+  const raw = fs.readFileSync(filePath, "utf-8");
+  const parsed = JSON.parse(raw);
+  return LockFileSchema.parse(parsed);
+}
+
+/**
+ * Serialize and write `catalog.lock.json`, creating the catalog directory
+ * if needed.
+ */
+export function writeLock(lock: LockFile, home?: string): void {
+  ensureCatalogDir(home);
+  const filePath = lockFile(home);
+  const content = JSON.stringify(lock, null, 2) + "\n";
+  fs.writeFileSync(filePath, content, "utf-8");
+}

package/src/config/paths.ts

@@ -0,0 +1,44 @@
+import path from "node:path";
+import fs from "node:fs";
+import os from "node:os";
+import { globalDir } from "@pi-stef/paths";
+
+/**
+ * ~/.pi/sf/catalog/
+ */
+export function catalogDir(home?: string): string {
+  return globalDir("catalog", home);
+}
+
+/**
+ * ~/.pi/sf/catalog/cat.yaml
+ */
+export function catalogFile(home?: string): string {
+  return path.join(catalogDir(home), "cat.yaml");
+}
+
+/**
+ * ~/.pi/sf/catalog/catalog.lock.json
+ */
+export function lockFile(home?: string): string {
+  return path.join(catalogDir(home), "catalog.lock.json");
+}
+
+/**
+ * Creates the catalog directory if it does not already exist.
+ */
+export function ensureCatalogDir(home?: string): void {
+  const dir = catalogDir(home);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+/**
+ * ~/.pi/agent/npm/node_modules
+ *
+ * Centralised so the npm node_modules path is not hardcoded in consumers.
+ */
+export function npmNodeModulesDir(home?: string): string {
+  return path.join(home ?? os.homedir(), ".pi", "agent", "npm", "node_modules");
+}

package/src/config/schema.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// cat.yaml schema
+// ---------------------------------------------------------------------------
+
+/** Type discriminator for a catalog package entry. */
+export const PackageType = z.enum(["skill", "pi-native"]);
+
+/** Rating values for catalog packages. */
+export const Rating = z.enum(["core", "useful", "debatable", "disabled"]);
+
+/** A single package entry inside cat.yaml. */
+export const CatalogPackageSchema = z.object({
+  /** Where to fetch the package from (URL, path, etc.). */
+  source: z.string().min(1),
+  /** User-assigned rating. */
+  rating: Rating,
+  /** Optional type discriminator. */
+  type: PackageType.optional(),
+  /** Optional profile name this package belongs to. */
+  profile: z.string().optional(),
+  /** Whether the package is active. Defaults to true when absent. */
+  enabled: z.boolean().optional(),
+  /** Previous rating before disable; used by enablePackage to restore. */
+  previousRating: Rating.optional(),
+});
+
+/** The meta section at the top of cat.yaml. */
+export const CatalogMetaSchema = z.object({
+  /** Minimum pi version this catalog requires. */
+  pi_version: z.string().min(1),
+  /** Currently active profile name. */
+  activeProfile: z.string().optional(),
+});
+
+/** A single named profile with its own package overrides. */
+export const ProfileSchema = z.object({
+  /** Packages specific to this profile (override base packages). */
+  packages: z.record(z.string(), CatalogPackageSchema),
+});
+
+/** Full cat.yaml document schema. */
+export const CatalogYamlSchema = z.object({
+  meta: CatalogMetaSchema,
+  packages: z.record(z.string(), CatalogPackageSchema),
+  /** Named profiles with package overrides. */
+  profiles: z.record(z.string(), ProfileSchema).optional(),
+});
+
+// ---------------------------------------------------------------------------
+// catalog.lock.json schema
+// ---------------------------------------------------------------------------
+
+/** Possible sync states for a locked package. */
+export const SyncState = z.enum(["synced", "outdated", "conflict"]);
+
+/** A single package entry inside catalog.lock.json. */
+export const LockPackageSchema = z.object({
+  /** Installed version string. */
+  version: z.string().min(1),
+  /** Deterministic hash derived from the source specifier (not installed file contents). */
+  sourceHash: z.string().min(1),
+  /** ISO-8601 timestamp of when the package was installed. */
+  installedAt: z.string().min(1),
+  /** Current synchronization state relative to the source. */
+  syncState: SyncState,
+});
+
+/** Full catalog.lock.json document schema. */
+export const LockFileSchema = z
+  .object({
+    packages: z.record(z.string(), LockPackageSchema),
+  })
+  .passthrough();
+
+// ---------------------------------------------------------------------------
+// Inferred TypeScript types
+// ---------------------------------------------------------------------------
+
+export type CatalogYaml = z.infer<typeof CatalogYamlSchema>;
+export type CatalogMeta = z.infer<typeof CatalogMetaSchema>;
+export type CatalogPackage = z.infer<typeof CatalogPackageSchema>;
+export type Profile = z.infer<typeof ProfileSchema>;
+export type LockFile = z.infer<typeof LockFileSchema>;
+export type LockPackage = z.infer<typeof LockPackageSchema>;
+export type RatingValue = z.infer<typeof Rating>;

package/src/index.ts

@@ -0,0 +1,94 @@
+// catalog
+export { scanInstalled, type InstalledPackage, type InstalledMap } from "./catalog/install.js";
+export {
+  reconcile,
+  executeActions,
+  type CatalogEntry,
+  type InstallAction,
+  type UninstallAction,
+  type UpgradeAction,
+  type OrphanReport,
+  type ReconcilePlan,
+  type ReconcileOptions,
+  type ActionError,
+  type ExecuteResult,
+  type ExecuteOptions,
+} from "./catalog/reconcile.js";
+export {
+  extractNpmName,
+  extractNpmVersion,
+  cleanGitName,
+  parseSource,
+  sourceToKey,
+  extractVersionFromSource,
+  type ParsedSource,
+} from "./catalog/source.js";
+
+// config
+export {
+  catalogDir,
+  catalogFile,
+  lockFile,
+  ensureCatalogDir,
+  npmNodeModulesDir,
+} from "./config/paths.js";
+export {
+  PackageType,
+  CatalogPackageSchema,
+  CatalogMetaSchema,
+  CatalogYamlSchema,
+  ProfileSchema,
+  SyncState,
+  LockPackageSchema,
+  LockFileSchema,
+  type CatalogYaml,
+  type CatalogMeta,
+  type CatalogPackage,
+  type LockFile,
+  type LockPackage,
+} from "./config/schema.js";
+
+// sync
+export { checkAuth, getToken } from "./sync/auth.js";
+export {
+  createGist,
+  readGist,
+  updateGist,
+  findGistByDescription,
+  _resetOctokit,
+  type GistFiles,
+  type GistResult,
+  type GistSummary,
+} from "./sync/gist.js";
+export {
+  gistCachePath,
+  readCachedGistId,
+  writeCachedGistId,
+} from "./sync/cache.js";
+export { pullCatalog, type PullResult } from "./sync/pull.js";
+export { pushCatalog, type PushResult } from "./sync/push.js";
+
+// util
+export {
+  execCommand,
+  piInstall,
+  piUninstall,
+  ExecError,
+  type ExecOptions,
+  type ExecResult,
+  type PiExecOptions,
+} from "./util/exec.js";
+
+// update
+export { checkSelfUpdate } from "./update/self-update.js";
+export { checkPiUpdate } from "./update/pi-update.js";
+export type { UpdateCheckResult, UpdateCacheEntry } from "./update/types.js";
+
+// profiles
+export {
+  DEFAULT_PROFILE,
+  createProfile,
+  switchProfile,
+  deleteProfile,
+  resolveEffectivePackages,
+} from "./profiles/manager.js";

package/src/profiles/manager.ts

@@ -0,0 +1,159 @@
+/**
+ * Profile manager for multi-profile catalog support.
+ *
+ * Profiles allow different package sets for different machines or contexts
+ * (e.g., work vs personal). Each profile has its own package overrides that
+ * merge over the base packages.
+ */
+
+import type { CatalogYaml, CatalogPackage } from "../config/schema.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Name of the default profile (always available). */
+export const DEFAULT_PROFILE = "default";
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/** Ensure the catalog has a profiles record, creating one if needed. */
+function ensureProfiles(catalog: CatalogYaml): CatalogYaml {
+  if (catalog.profiles === undefined) {
+    return { ...catalog, profiles: {} };
+  }
+  return catalog;
+}
+
+// ---------------------------------------------------------------------------
+// createProfile
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a new empty profile.
+ *
+ * @throws if a profile with the given name already exists
+ */
+export function createProfile(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  if (name === DEFAULT_PROFILE) {
+    throw new Error(`The "${DEFAULT_PROFILE}" profile always exists`);
+  }
+
+  const withProfiles = ensureProfiles(catalog);
+
+  if (withProfiles.profiles![name]) {
+    throw new Error(`Profile "${name}" already exists`);
+  }
+
+  return {
+    ...withProfiles,
+    profiles: {
+      ...withProfiles.profiles!,
+      [name]: { packages: {} },
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// switchProfile
+// ---------------------------------------------------------------------------
+
+/**
+ * Switch the active profile.
+ *
+ * @throws if the target profile does not exist
+ */
+export function switchProfile(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  if (name !== DEFAULT_PROFILE) {
+    if (!catalog.profiles?.[name]) {
+      throw new Error(`Profile "${name}" not found`);
+    }
+  }
+
+  return {
+    ...catalog,
+    meta: {
+      ...catalog.meta,
+      activeProfile: name,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// deleteProfile
+// ---------------------------------------------------------------------------
+
+/**
+ * Delete a profile.
+ *
+ * @throws if the profile does not exist
+ * @throws if attempting to delete the default profile
+ */
+export function deleteProfile(
+  catalog: CatalogYaml,
+  name: string,
+): CatalogYaml {
+  if (name === DEFAULT_PROFILE) {
+    throw new Error(`Cannot delete the "${DEFAULT_PROFILE}" profile`);
+  }
+
+  if (!catalog.profiles?.[name]) {
+    throw new Error(`Profile "${name}" not found`);
+  }
+
+  const { [name]: _, ...remainingProfiles } = catalog.profiles;
+
+  // Clear activeProfile if it was the deleted profile
+  const meta = { ...catalog.meta };
+  if (meta.activeProfile === name) {
+    delete meta.activeProfile;
+  }
+
+  return {
+    ...catalog,
+    meta,
+    profiles: remainingProfiles,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// resolveEffectivePackages
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the effective package set by merging base packages with
+ * the active (or specified) profile's overrides.
+ *
+ * Profile packages override base packages with the same key.
+ * If no profile is specified, uses `meta.activeProfile` (falling back
+ * to `DEFAULT_PROFILE`).
+ */
+export function resolveEffectivePackages(
+  catalog: CatalogYaml,
+  profile?: string,
+): Record<string, CatalogPackage> {
+  const profileName = profile ?? catalog.meta.activeProfile ?? DEFAULT_PROFILE;
+
+  // Start with a shallow clone of base packages
+  const result: Record<string, CatalogPackage> = { ...catalog.packages };
+
+  // Merge profile overrides on top
+  if (profileName !== DEFAULT_PROFILE) {
+    const profilePkgs = catalog.profiles?.[profileName]?.packages;
+    if (profilePkgs) {
+      for (const [key, value] of Object.entries(profilePkgs)) {
+        result[key] = value;
+      }
+    }
+  }
+
+  return result;
+}