@appstrate/core 1.0.1 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/core",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "type": "module",
   "files": ["src"],
   "exports": {
@@ -8,23 +8,27 @@
     "./rate-limit": "./src/rate-limit.ts",
     "./env": "./src/env.ts",
     "./storage": "./src/storage.ts",
-    "./errors": "./src/errors.ts"
+    "./errors": "./src/errors.ts",
+    "./validation": "./src/validation.ts",
+    "./zip": "./src/zip.ts",
+    "./naming": "./src/naming.ts",
+    "./dependencies": "./src/dependencies.ts",
+    "./integrity": "./src/integrity.ts",
+    "./semver": "./src/semver.ts",
+    "./registry-deps": "./src/registry-deps.ts",
+    "./update-check": "./src/update-check.ts",
+    "./publish-manifest": "./src/publish-manifest.ts"
   },
   "dependencies": {
+    "fflate": "^0.8.0",
     "pino": "^10.3.1",
+    "semver": "^7.7.1",
     "zod": "^4.3.6"
   },
-  "scripts": {
-    "check": "tsc --noEmit && eslint src/ && prettier --check src/",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix && prettier --write src/",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "test": "bun test"
-  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/bun": "latest",
+    "@types/semver": "^7.5.8",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "globals": "^17.3.0",
@@ -33,5 +37,13 @@
   },
   "peerDependencies": {
     "typescript": "^5"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && eslint src/ && prettier --check src/",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix && prettier --write src/",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "bun test"
   }
 }

package/src/dependencies.ts

@@ -0,0 +1,120 @@
+import { parseScopedName } from "./naming.ts";
+
+export interface DepEntry {
+  depScope: string;
+  depName: string;
+  depType: "skill" | "extension";
+  versionRange: string;
+}
+
+export function extractDependencies(manifest: Record<string, unknown>): DepEntry[] {
+  const registryDependencies = manifest.registryDependencies as
+    | {
+        skills?: Record<string, string>;
+        extensions?: Record<string, string>;
+      }
+    | undefined;
+
+  if (!registryDependencies) return [];
+
+  const deps: DepEntry[] = [];
+
+  const { skills = {}, extensions = {} } = registryDependencies;
+
+  const maps: [Record<string, string>, DepEntry["depType"]][] = [
+    [skills, "skill"],
+    [extensions, "extension"],
+  ];
+
+  for (const [map, depType] of maps) {
+    for (const [fullName, versionRange] of Object.entries(map)) {
+      const parsed = parseScopedName(fullName);
+      if (!parsed) {
+        throw new Error(`Invalid scoped package name: ${fullName}`);
+      }
+      deps.push({ depScope: `@${parsed.scope}`, depName: parsed.name, depType, versionRange });
+    }
+  }
+
+  return deps;
+}
+
+export interface CycleCheckResult {
+  hasCycle: boolean;
+  /** The cycle path if found, e.g. ["@a/pkg", "@b/pkg", "@a/pkg"] */
+  cyclePath?: string[];
+}
+
+/**
+ * BFS-based circular dependency detection.
+ * @param publishingId — The package being published/installed (e.g. "@scope/name")
+ * @param directDeps — Its direct dependencies
+ * @param resolveDeps — Async callback to fetch transitive deps of a package
+ */
+export async function detectCycle(
+  publishingId: string,
+  directDeps: DepEntry[],
+  resolveDeps: (scope: string, name: string) => Promise<DepEntry[]>,
+): Promise<CycleCheckResult> {
+  // Fast path: self-reference
+  for (const dep of directDeps) {
+    const depId = `${dep.depScope}/${dep.depName}`;
+    if (depId === publishingId) {
+      return { hasCycle: true, cyclePath: [publishingId, depId] };
+    }
+  }
+
+  // BFS traversal
+  const visited = new Set<string>();
+  const parent = new Map<string, string>();
+  const queue: string[] = directDeps.map((d) => `${d.depScope}/${d.depName}`);
+
+  for (const depId of queue) {
+    parent.set(depId, publishingId);
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    // Parse scope/name from the key (format: "@scope/name")
+    const slashIdx = current.indexOf("/", 1); // skip @ prefix
+    if (slashIdx === -1) continue;
+    const scope = current.slice(0, slashIdx);
+    const name = current.slice(slashIdx + 1);
+
+    let transitiveDeps: DepEntry[];
+    try {
+      transitiveDeps = await resolveDeps(scope, name);
+    } catch {
+      continue;
+    }
+
+    for (const dep of transitiveDeps) {
+      const depId = `${dep.depScope}/${dep.depName}`;
+
+      if (depId === publishingId) {
+        // Reconstruct cycle path
+        const path: string[] = [publishingId];
+        let node: string | undefined = current;
+        const chain: string[] = [];
+        while (node && node !== publishingId) {
+          chain.unshift(node);
+          node = parent.get(node);
+        }
+        path.push(...chain, depId);
+        return { hasCycle: true, cyclePath: path };
+      }
+
+      if (!visited.has(depId)) {
+        queue.push(depId);
+        if (!parent.has(depId)) {
+          parent.set(depId, current);
+        }
+      }
+    }
+  }
+
+  return { hasCycle: false };
+}

package/src/integrity.ts

@@ -0,0 +1,6 @@
+export function computeIntegrity(data: Uint8Array | Buffer): string {
+  const hash = new Bun.CryptoHasher("sha256");
+  hash.update(data);
+  const base64 = hash.digest("base64");
+  return `sha256-${base64}`;
+}

package/src/naming.ts

@@ -0,0 +1,27 @@
+export const SLUG_PATTERN = "[a-z0-9]([a-z0-9-]*[a-z0-9])?";
+export const SLUG_REGEX = new RegExp(`^${SLUG_PATTERN}$`);
+
+export function normalizeScope(scope: string): string {
+  if (!scope) throw new Error("Scope cannot be empty");
+  return scope.startsWith("@") ? scope : `@${scope}`;
+}
+
+export function stripScope(scope: string): string {
+  return scope.startsWith("@") ? scope.slice(1) : scope;
+}
+
+/** Parse "@scope/name" into { scope, name } or null if invalid.
+ *  Both scope and name must be valid slugs (lowercase alphanumeric + hyphens). */
+const SCOPED_NAME_REGEX = new RegExp(`^@(${SLUG_PATTERN})\\/(${SLUG_PATTERN})$`);
+
+export function parseScopedName(scopedName: string): { scope: string; name: string } | null {
+  const match = scopedName.match(SCOPED_NAME_REGEX);
+  if (!match) return null;
+  return { scope: match[1]!, name: match[3]! };
+}
+
+/** Build a packageId from separated scope + name. */
+export function buildPackageId(scope: string, name: string): string {
+  const s = stripScope(scope);
+  return `@${s}/${name}`;
+}

package/src/publish-manifest.ts

@@ -0,0 +1,24 @@
+import type { RegistryDependencies } from "./registry-deps.ts";
+
+/** Prepare a manifest for registry publication by overriding name, version, and deps. */
+export function prepareManifestForPublish(
+  currentManifest: Record<string, unknown>,
+  scope: string,
+  name: string,
+  version: string,
+  registryDeps: RegistryDependencies | null,
+): Record<string, unknown> {
+  const manifest: Record<string, unknown> = {
+    ...currentManifest,
+    name: `@${scope}/${name}`,
+    version,
+  };
+
+  if (registryDeps) {
+    manifest.registryDependencies = registryDeps;
+  } else {
+    delete manifest.registryDependencies;
+  }
+
+  return manifest;
+}

package/src/registry-deps.ts

@@ -0,0 +1,41 @@
+export interface PackageRegistryRow {
+  type: string;
+  registryScope: string | null;
+  registryName: string | null;
+  lastPublishedVersion: string | null;
+}
+
+export interface RegistryDependencies {
+  skills?: Record<string, string>;
+  extensions?: Record<string, string>;
+}
+
+/** Transform DB rows into registryDependencies format for manifest.
+ *  Skips rows without registryScope/registryName.
+ *  Returns null if no registry-linked dependencies found. */
+export function buildRegistryDepsFromRows(rows: PackageRegistryRow[]): RegistryDependencies | null {
+  const skills: Record<string, string> = {};
+  const extensions: Record<string, string> = {};
+
+  for (const row of rows) {
+    if (!row.registryScope || !row.registryName) continue;
+
+    const scopedName = `@${row.registryScope}/${row.registryName}`;
+    const version = row.lastPublishedVersion || "*";
+
+    if (row.type === "skill") {
+      skills[scopedName] = version;
+    } else if (row.type === "extension") {
+      extensions[scopedName] = version;
+    }
+  }
+
+  const hasSkills = Object.keys(skills).length > 0;
+  const hasExtensions = Object.keys(extensions).length > 0;
+  if (!hasSkills && !hasExtensions) return null;
+
+  const result: RegistryDependencies = {};
+  if (hasSkills) result.skills = skills;
+  if (hasExtensions) result.extensions = extensions;
+  return result;
+}

package/src/semver.ts

@@ -0,0 +1,73 @@
+import semver from "semver";
+
+/** Check whether `v` is a valid semver version string. */
+export function isValidVersion(v: string): boolean {
+  return semver.valid(v) !== null;
+}
+
+/** Check whether `v` is a valid semver range string. */
+export function isValidRange(v: string): boolean {
+  return semver.validRange(v) !== null;
+}
+
+/** Return `true` if version `a` is strictly greater than version `b`. Returns `false` if either is invalid. */
+export function versionGt(a: string, b: string): boolean {
+  try {
+    return semver.gt(a, b);
+  } catch {
+    return false;
+  }
+}
+
+/** Comparator for sorting versions in descending order (highest first). */
+export function compareVersionsDesc(a: string, b: string): number {
+  return semver.rcompare(a, b);
+}
+
+/** Find the highest version in `versions` that satisfies `range`, or `null` if none match. */
+export function matchVersion(versions: string[], range: string): string | null {
+  return semver.maxSatisfying(versions, range);
+}
+
+/** Return `true` if `v` is a prerelease version (e.g. `1.0.0-beta.1`). */
+export function isPrerelease(v: string): boolean {
+  return semver.prerelease(v) !== null;
+}
+
+/** Returns true if `remote` is a strictly newer version than `installed`.
+ *  Returns false if either is null/undefined or invalid. */
+export function hasNewerVersion(
+  installed: string | null | undefined,
+  remote: string | null | undefined,
+): boolean {
+  if (!installed || !remote) return false;
+  if (!isValidVersion(installed) || !isValidVersion(remote)) return false;
+  return versionGt(remote, installed);
+}
+
+export interface VersionWithId {
+  id: number;
+  version: string;
+}
+
+export interface DistTagEntry {
+  tag: string;
+  versionId: number;
+}
+
+/** Resolve latest version from dist-tags + versions list.
+ *  Priority: "latest" dist-tag → last entry in versions array. */
+export function resolveLatestVersion(
+  versions: VersionWithId[],
+  distTags: DistTagEntry[],
+): string | null {
+  if (versions.length === 0) return null;
+
+  const latestTag = distTags.find((t) => t.tag === "latest");
+  if (latestTag) {
+    const tagged = versions.find((v) => v.id === latestTag.versionId);
+    if (tagged) return tagged.version;
+  }
+
+  return versions.at(-1)?.version ?? null;
+}

package/src/update-check.ts

@@ -0,0 +1,22 @@
+import { hasNewerVersion, resolveLatestVersion } from "./semver.ts";
+import type { VersionWithId, DistTagEntry } from "./semver.ts";
+
+export type { VersionWithId, DistTagEntry };
+
+export interface UpdateCheckInput {
+  installedVersion: string | null;
+  remoteVersions: VersionWithId[];
+  remoteDistTags: DistTagEntry[];
+}
+
+export interface UpdateCheckResult {
+  latestVersion: string | null;
+  updateAvailable: boolean;
+}
+
+/** Check if an update is available for an installed package. */
+export function checkUpdateAvailable(input: UpdateCheckInput): UpdateCheckResult {
+  const latestVersion = resolveLatestVersion(input.remoteVersions, input.remoteDistTags);
+  const updateAvailable = hasNewerVersion(input.installedVersion, latestVersion);
+  return { latestVersion, updateAvailable };
+}

package/src/validation.ts

@@ -0,0 +1,302 @@
+import { z } from "zod";
+import semver from "semver";
+import { SLUG_REGEX, SLUG_PATTERN } from "./naming.ts";
+
+export { SLUG_REGEX };
+
+const flowFieldTypeEnum = z.enum(["string", "number", "boolean", "array", "object", "file"]);
+
+export const jsonSchemaPropertySchema = z.object({
+  type: flowFieldTypeEnum,
+  description: z.string().optional(),
+  default: z.unknown().optional(),
+  enum: z.array(z.unknown()).optional(),
+  format: z.string().optional(),
+  placeholder: z.string().optional(),
+  accept: z.string().optional(),
+  maxSize: z.number().positive().optional(),
+  multiple: z.boolean().optional(),
+  maxFiles: z.number().int().positive().optional(),
+});
+
+export const jsonSchemaObjectSchema = z.object({
+  type: z.literal("object"),
+  properties: z.record(z.string(), jsonSchemaPropertySchema),
+  required: z.array(z.string()).optional(),
+  propertyOrder: z.array(z.string()).optional(),
+});
+
+export const serviceRequirementSchema = z.looseObject({
+  id: z.string().min(1).regex(SLUG_REGEX, {
+    error: "Must be a valid slug (a-z, 0-9, hyphens, no leading/trailing hyphen)",
+  }),
+  provider: z.string(),
+  description: z.string().optional(),
+  scopes: z.array(z.string()).optional(),
+  connectionMode: z.enum(["user", "admin"]).optional(),
+});
+
+export const PACKAGE_REF_REGEX = new RegExp(`^(?:@${SLUG_PATTERN}\\/)?${SLUG_PATTERN}$`);
+
+const packageRefString = z.string().min(1).regex(PACKAGE_REF_REGEX, {
+  error: "Must be a valid slug or scoped name (@scope/name)",
+});
+
+const semverRangeString = z.string().refine((val) => semver.validRange(val) !== null, {
+  error: "Must be a valid semver range (e.g. ^1.0.0, ~2.1, >=3.0.0)",
+});
+
+const registryDependenciesSchema = z
+  .looseObject({
+    skills: z.record(z.string(), semverRangeString).optional(),
+    extensions: z.record(z.string(), semverRangeString).optional(),
+  })
+  .optional();
+
+// ─────────────────────────────────────────────
+// Base manifest schema — common fields for all package types
+// ─────────────────────────────────────────────
+
+export const scopedNameRegex = new RegExp(`^@${SLUG_PATTERN}\\/${SLUG_PATTERN}$`);
+export const packageTypeEnum = z.enum(["flow", "skill", "extension"]);
+export type PackageType = z.infer<typeof packageTypeEnum>;
+
+export const manifestSchema = z.looseObject({
+  name: z.string().regex(scopedNameRegex, { error: "Must follow the format @scope/package-name" }),
+  version: z.string().refine((v) => semver.valid(v) !== null, {
+    error: "Must be a valid semver version",
+  }),
+  type: packageTypeEnum,
+  displayName: z.string().optional().catch(undefined),
+  description: z.string().optional().catch(undefined),
+  keywords: z.array(z.string()).optional().catch(undefined),
+  license: z.string().optional().catch(undefined),
+  repository: z.string().optional().catch(undefined),
+  readme: z.string().optional().catch(undefined),
+  registryDependencies: registryDependenciesSchema,
+});
+
+export type Manifest = z.infer<typeof manifestSchema>;
+
+// ─── Sub-schema inferred types ───────────────
+
+export type FlowServiceRequirement = z.infer<typeof serviceRequirementSchema>;
+export type FlowJsonSchemaProperty = z.infer<typeof jsonSchemaPropertySchema>;
+export type FlowJsonSchemaObject = z.infer<typeof jsonSchemaObjectSchema>;
+
+// ─────────────────────────────────────────────
+// Shared flow fields
+// ─────────────────────────────────────────────
+
+const flowSharedFields = {
+  requires: z.looseObject({
+    services: z.array(serviceRequirementSchema),
+    skills: z.array(packageRefString).optional(),
+    extensions: z.array(packageRefString).optional(),
+  }),
+  input: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  output: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  config: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  execution: z
+    .looseObject({
+      timeout: z.number().optional(),
+      outputRetries: z.number().min(0).max(5).optional(),
+    })
+    .optional(),
+} as const;
+
+// ─────────────────────────────────────────────
+// Flow manifest schema — extends base with flow-specific fields
+// ─────────────────────────────────────────────
+
+export const flowManifestSchema = manifestSchema.extend({
+  $schema: z.string().optional(),
+  schemaVersion: z.string(),
+  displayName: z.string().min(1),
+  author: z.string(),
+  tags: z.array(z.string()).optional(),
+  ...flowSharedFields,
+});
+
+export type FlowManifest = z.infer<typeof flowManifestSchema>;
+
+// ─────────────────────────────────────────────
+// Unified validateManifest — dispatches by type
+// ─────────────────────────────────────────────
+
+export type ValidateManifestResult =
+  | { valid: true; errors: []; manifest: Manifest | FlowManifest }
+  | { valid: false; errors: string[]; manifest?: undefined };
+
+function parseWithSchema(
+  schema: typeof manifestSchema | typeof flowManifestSchema,
+  raw: unknown,
+): ValidateManifestResult {
+  const result = schema.safeParse(raw);
+  if (result.success) {
+    return { valid: true, errors: [], manifest: result.data };
+  }
+  const errors = result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+  return { valid: false, errors };
+}
+
+export function validateManifest(raw: unknown): ValidateManifestResult {
+  if (raw && typeof raw === "object" && "type" in raw) {
+    const schema =
+      (raw as Record<string, unknown>).type === "flow" ? flowManifestSchema : manifestSchema;
+    return parseWithSchema(schema, raw);
+  }
+  return { valid: false, errors: ["type: Required field is missing"] };
+}
+
+function stripQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+
+export function extractSkillMeta(content: string): {
+  name: string;
+  description: string;
+  warnings: string[];
+} {
+  const warnings: string[] = [];
+  const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
+  if (!fmMatch) {
+    warnings.push("No YAML frontmatter detected (expected --- ... --- block)");
+    return { name: "", description: "", warnings };
+  }
+
+  const fm = fmMatch[1]!;
+  const nameMatch = fm.match(/name:\s*(.+)/);
+  const descMatch = fm.match(/description:\s*(.+)/);
+
+  const name = nameMatch ? stripQuotes(nameMatch[1]!) : "";
+  const description = descMatch ? stripQuotes(descMatch[1]!) : "";
+
+  if (!name) {
+    warnings.push("Missing 'name' field in YAML frontmatter");
+  }
+  if (!description) {
+    warnings.push("Missing 'description' field in YAML frontmatter");
+  }
+
+  return { name, description, warnings };
+}
+
+export interface ExtensionValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+function stripLineComments(source: string): string {
+  return source.replace(/\/\/.*$/gm, "");
+}
+
+function countParams(paramStr: string): number {
+  const trimmed = paramStr.trim();
+  if (trimmed === "") return 0;
+
+  let depth = 0;
+  let count = 1;
+  for (const ch of trimmed) {
+    if (ch === "<" || ch === "(") depth++;
+    else if (ch === ">" || ch === ")") depth--;
+    else if (ch === "," && depth === 0) count++;
+  }
+  return count;
+}
+
+export interface ManifestMetadata {
+  description?: string;
+  keywords?: string[];
+  license?: string;
+  repositoryUrl?: string;
+  readme?: string;
+}
+
+/** Extract optional metadata fields from a manifest.
+ *  Maps `repository` to `repositoryUrl` to match the DB column convention. */
+export function extractManifestMetadata(manifest: Partial<Manifest>): ManifestMetadata {
+  const metadata: ManifestMetadata = {};
+  if (manifest.description !== undefined) metadata.description = manifest.description;
+  if (manifest.keywords !== undefined) metadata.keywords = manifest.keywords;
+  if (manifest.license !== undefined) metadata.license = manifest.license as string;
+  if (manifest.repository !== undefined) metadata.repositoryUrl = manifest.repository as string;
+  if (manifest.readme !== undefined) metadata.readme = manifest.readme as string;
+  return metadata;
+}
+
+export function validateExtensionSource(source: string): ExtensionValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (source.trim().length === 0) {
+    return { valid: false, errors: ["Extension content is empty"], warnings };
+  }
+
+  if (!/export\s+default\b/.test(source)) {
+    errors.push(
+      "Extension must have an `export default function`. " +
+        "Example: export default function(pi: ExtensionAPI) { ... }",
+    );
+  }
+
+  if (!/\.registerTool\s*\(/.test(source)) {
+    warnings.push(
+      "Extension does not call `pi.registerTool()`. " + "Make sure to register at least one tool.",
+    );
+  }
+
+  const cleaned = stripLineComments(source);
+  const executeMatches = [...cleaned.matchAll(/execute\s*\(([^)]*)\)/g)];
+  for (const match of executeMatches) {
+    const paramStr = match[1]!;
+    const paramCount = countParams(paramStr);
+    if (paramCount === 1) {
+      errors.push(
+        "The `execute` signature has only one parameter. " +
+          "The Pi SDK calls execute(toolCallId, params, signal) — with a single parameter, " +
+          "your function will receive the toolCallId (string) instead of params. " +
+          "Fix: execute(_toolCallId, params, signal) { ... }",
+      );
+      break;
+    }
+  }
+
+  if (executeMatches.length > 0 && !/content\s*:/.test(cleaned)) {
+    warnings.push(
+      "The `execute` function does not seem to return `{ content: [...] }`. " +
+        'Expected format: { content: [{ type: "text", text: "..." }] }',
+    );
+  }
+
+  let braceCount = 0;
+  for (const ch of cleaned) {
+    if (ch === "{") braceCount++;
+    else if (ch === "}") braceCount--;
+  }
+  if (braceCount !== 0) {
+    errors.push(`Probable syntax error: braces are not balanced (difference: ${braceCount})`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/zip.ts

@@ -0,0 +1,195 @@
+import { unzipSync, zipSync, type Zippable } from "fflate";
+import {
+  validateManifest,
+  extractSkillMeta,
+  validateExtensionSource,
+  type Manifest,
+  type FlowManifest,
+} from "./validation.ts";
+
+export type { Zippable };
+
+export function zipArtifact(
+  entries: Zippable,
+  level: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 = 6,
+): Uint8Array {
+  return zipSync(entries, { level });
+}
+
+interface UnzippedArtifact {
+  files: Record<string, Uint8Array>;
+  prefix: string;
+}
+
+export function unzipArtifact(artifact: Uint8Array): UnzippedArtifact {
+  let rawFiles: Record<string, Uint8Array>;
+  try {
+    rawFiles = unzipSync(artifact);
+  } catch {
+    throw new Error("Failed to decompress ZIP artifact");
+  }
+
+  // Sanitize: filter out path traversal, absolute paths, null bytes, __MACOSX, and directory entries
+  const files: Record<string, Uint8Array> = {};
+  for (const [key, value] of Object.entries(rawFiles)) {
+    if (key.includes("..") || key.startsWith("/") || key.includes("\0")) continue;
+    if (key.startsWith("__MACOSX/") || key.endsWith("/")) continue;
+    files[key] = value;
+  }
+
+  const entries = Object.keys(files);
+  const prefix = detectFolderWrapper(entries);
+
+  return { files, prefix };
+}
+
+export function detectFolderWrapper(entries: string[]): string {
+  // Filter out __MACOSX and directory entries before detection
+  const filtered = entries.filter((e) => !e.startsWith("__MACOSX/") && !e.endsWith("/"));
+  if (filtered.length === 0) return "";
+  const first = filtered[0];
+  if (!first) return "";
+  const firstDir = first.split("/")[0];
+  if (!firstDir) return "";
+  return filtered.every((e) => e.startsWith(firstDir + "/")) ? firstDir + "/" : "";
+}
+
+function getFileText(
+  files: Record<string, Uint8Array>,
+  prefix: string,
+  name: string,
+): string | undefined {
+  const data = files[prefix + name] ?? files[name];
+  return data ? new TextDecoder().decode(data) : undefined;
+}
+
+// ─────────────────────────────────────────────
+// Unified package ZIP parser — handles flow, skill, extension
+// ─────────────────────────────────────────────
+
+export interface ParsedPackageZip {
+  manifest: Manifest | FlowManifest;
+  content: string;
+  files: Record<string, Uint8Array>;
+  type: "flow" | "skill" | "extension";
+}
+
+export class PackageZipError extends Error {
+  constructor(
+    public code: string,
+    message: string,
+    public details?: unknown,
+  ) {
+    super(message);
+    this.name = "PackageZipError";
+  }
+}
+
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+
+export function parsePackageZip(zipBuffer: Uint8Array, maxSize?: number): ParsedPackageZip {
+  const limit = maxSize ?? DEFAULT_MAX_SIZE;
+  if (zipBuffer.length > limit) {
+    throw new PackageZipError(
+      "FILE_TOO_LARGE",
+      `ZIP exceeds maximum size of ${limit / 1024 / 1024} MB`,
+    );
+  }
+
+  let files: Record<string, Uint8Array>;
+  let prefix: string;
+  try {
+    const result = unzipArtifact(zipBuffer);
+    files = result.files;
+    prefix = result.prefix;
+  } catch {
+    throw new PackageZipError("ZIP_INVALID", "Failed to decompress ZIP artifact");
+  }
+
+  // Zip bomb protection: check total decompressed size
+  const MAX_DECOMPRESSED = 50 * 1024 * 1024; // 50 MB
+  const totalSize = Object.values(files).reduce((sum, buf) => sum + buf.length, 0);
+  if (totalSize > MAX_DECOMPRESSED) {
+    throw new PackageZipError(
+      "ZIP_BOMB",
+      `Decompressed size (${(totalSize / 1024 / 1024).toFixed(1)} MB) exceeds limit`,
+    );
+  }
+
+  // Parse manifest.json
+  const manifestText = getFileText(files, prefix, "manifest.json");
+  if (!manifestText) {
+    throw new PackageZipError("MISSING_MANIFEST", "manifest.json not found in ZIP");
+  }
+
+  let manifestRaw: unknown;
+  try {
+    manifestRaw = JSON.parse(manifestText);
+  } catch {
+    throw new PackageZipError("INVALID_MANIFEST", "manifest.json is not valid JSON");
+  }
+
+  const validation = validateManifest(manifestRaw);
+  if (!validation.valid) {
+    const detail = validation.errors.join("; ");
+    throw new PackageZipError(
+      "INVALID_MANIFEST",
+      detail ? `Manifest validation failed: ${detail}` : "Manifest validation failed",
+      validation.errors,
+    );
+  }
+
+  const manifest = validation.manifest!;
+
+  const type = manifest.type;
+
+  // Extract primary content based on type
+  let content: string;
+
+  switch (type) {
+    case "flow": {
+      const promptMd = getFileText(files, prefix, "prompt.md");
+      if (!promptMd || promptMd.trim().length === 0) {
+        throw new PackageZipError("MISSING_CONTENT", "Flow package must contain prompt.md");
+      }
+      content = promptMd;
+      break;
+    }
+    case "skill": {
+      const skillMd = getFileText(files, prefix, "SKILL.md");
+      if (!skillMd) {
+        throw new PackageZipError("MISSING_CONTENT", "Skill package must contain SKILL.md");
+      }
+      const meta = extractSkillMeta(skillMd);
+      if (!meta.name) {
+        throw new PackageZipError(
+          "INVALID_CONTENT",
+          "SKILL.md must contain a 'name' in YAML frontmatter",
+        );
+      }
+      content = skillMd;
+      break;
+    }
+    case "extension": {
+      const tsEntry = Object.keys(files).find((f) => {
+        const name = prefix && f.startsWith(prefix) ? f.slice(prefix.length) : f;
+        return name.endsWith(".ts") && !name.endsWith(".d.ts") && !name.includes("/");
+      });
+      if (!tsEntry) {
+        throw new PackageZipError("MISSING_CONTENT", "Extension package must contain a .ts file");
+      }
+      const source = new TextDecoder().decode(files[tsEntry]!);
+      const extValidation = validateExtensionSource(source);
+      if (!extValidation.valid) {
+        throw new PackageZipError(
+          "INVALID_CONTENT",
+          `Extension validation failed: ${extValidation.errors.join("; ")}`,
+        );
+      }
+      content = source;
+      break;
+    }
+  }
+
+  return { manifest, content, files, type };
+}