@appstrate/validation 1.0.0

package/README.md

@@ -0,0 +1 @@
+# validation

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@appstrate/validation",
+  "version": "1.0.0",
+  "type": "module",
+  "files": ["src"],
+  "exports": {
+    ".": "./src/index.ts",
+    "./zip": "./src/zip.ts",
+    "./integrity": "./src/integrity.ts",
+    "./naming": "./src/naming.ts",
+    "./dependencies": "./src/dependencies.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "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/"
+  },
+  "dependencies": {
+    "fflate": "^0.8.0",
+    "semver": "^7.7.1",
+    "zod": "^4.3.6"
+  },
+  "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",
+    "prettier": "^3.8.1",
+    "typescript-eslint": "^8.55.0"
+  }
+}

package/src/dependencies.ts

@@ -0,0 +1,43 @@
+export interface DepEntry {
+  depScope: string;
+  depName: string;
+  depType: "skill" | "extension";
+  versionRange: string;
+}
+
+export function extractDependencies(manifest: Record<string, unknown>): DepEntry[] {
+  const requires = manifest.requires as
+    | {
+        registryDependencies?: {
+          skills?: Record<string, string>;
+          extensions?: Record<string, string>;
+        };
+      }
+    | undefined;
+
+  if (!requires?.registryDependencies) return [];
+
+  const deps: DepEntry[] = [];
+
+  const { skills = {}, extensions = {} } = requires.registryDependencies;
+
+  for (const [fullName, versionRange] of Object.entries(skills)) {
+    const { scope, name } = parseScopedName(fullName);
+    deps.push({ depScope: scope, depName: name, depType: "skill", versionRange });
+  }
+
+  for (const [fullName, versionRange] of Object.entries(extensions)) {
+    const { scope, name } = parseScopedName(fullName);
+    deps.push({ depScope: scope, depName: name, depType: "extension", versionRange });
+  }
+
+  return deps;
+}
+
+function parseScopedName(fullName: string): { scope: string; name: string } {
+  const match = fullName.match(/^(@[a-z0-9-]+)\/([a-z0-9-]+)$/);
+  if (!match) {
+    throw new Error(`Invalid scoped package name: ${fullName}`);
+  }
+  return { scope: match[1]!, name: match[2]! };
+}

package/src/index.ts

@@ -0,0 +1,344 @@
+import { z } from "zod";
+import semver from "semver";
+
+export const SLUG_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+const flowFieldTypeEnum = z.enum(["string", "number", "boolean", "array", "object", "file"]);
+
+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(),
+});
+
+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(),
+});
+
+const serviceRequirementSchema = z.object({
+  id: z.string().min(1).regex(SLUG_REGEX, {
+    error: "Doit etre un slug valide (a-z, 0-9, tirets, pas de tiret en debut/fin)",
+  }),
+  provider: z.string(),
+  scopes: z.array(z.string()).optional().default([]),
+  connectionMode: z.enum(["user", "admin"]).optional().default("user"),
+});
+
+const slugString = z.string().min(1).regex(SLUG_REGEX, {
+  error: "Doit etre un slug valide (a-z, 0-9, tirets, pas de tiret en debut/fin)",
+});
+
+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
+  .object({
+    skills: z.record(z.string(), semverRangeString).optional().default({}),
+    extensions: z.record(z.string(), semverRangeString).optional().default({}),
+  })
+  .optional();
+
+// ─────────────────────────────────────────────
+// Base manifest schema — common fields for all package types
+// ─────────────────────────────────────────────
+
+const scopedNameRegex = /^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+const packageTypeEnum = z.enum(["flow", "skill", "extension"]);
+
+export const baseManifestSchema = z.object({
+  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,
+  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 BaseManifest = z.infer<typeof baseManifestSchema>;
+
+// ─────────────────────────────────────────────
+// Flow manifest schema — extends base with flow-specific fields
+// ─────────────────────────────────────────────
+
+export const flowManifestSchema = baseManifestSchema.extend({
+  $schema: z.string().optional(),
+  schemaVersion: z.string(),
+  displayName: z.string().min(1),
+  author: z.string(),
+  tags: z.array(z.string()).optional(),
+  requires: z.object({
+    services: z.array(serviceRequirementSchema),
+    skills: z.array(slugString).optional().default([]),
+    extensions: z.array(slugString).optional().default([]),
+    registryDependencies: registryDependenciesSchema,
+  }),
+  input: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  output: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  config: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  execution: z
+    .object({
+      timeout: z.number().optional(),
+      outputRetries: z.number().min(0).max(5).optional(),
+    })
+    .optional(),
+});
+
+export type FlowManifest = z.infer<typeof flowManifestSchema>;
+
+// Keep backward compat — the old manifestSchema was used for flow validation only
+export const manifestSchema = flowManifestSchema;
+export type ManifestSchema = FlowManifest;
+
+// ─────────────────────────────────────────────
+// Unified validateManifest — dispatches by type
+// ─────────────────────────────────────────────
+
+export function validateManifest(raw: unknown): {
+  valid: boolean;
+  errors: string[];
+  manifest?: unknown;
+} {
+  // First, check if it has a type field to dispatch
+  if (raw && typeof raw === "object" && "type" in raw) {
+    const obj = raw as Record<string, unknown>;
+
+    if (obj.type === "flow") {
+      return validateFlowManifest(raw);
+    }
+
+    // For skill/extension, validate with base schema only
+    const result = baseManifestSchema.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 };
+  }
+
+  // No type field — try flow manifest validation (backward compat for flow-only manifests
+  // that don't have name/version/type because they rely on the old format)
+  return validateFlowManifest(raw);
+}
+
+function validateFlowManifest(raw: unknown): {
+  valid: boolean;
+  errors: string[];
+  manifest?: unknown;
+} {
+  const result = flowManifestSchema.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 };
+}
+
+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("Pas de frontmatter YAML detecte (bloc --- ... --- attendu)");
+    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("Champ 'name' manquant dans le frontmatter YAML");
+  }
+  if (!description) {
+    warnings.push("Champ 'description' manquant dans le frontmatter YAML");
+  }
+
+  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;
+}
+
+// ─────────────────────────────────────────────
+// Local flow manifest schema — relaxed for strate (no scoped name, optional version)
+// ─────────────────────────────────────────────
+
+export const localFlowManifestSchema = z.looseObject({
+  $schema: z.string().optional(),
+  schemaVersion: z.string(),
+  name: slugString,
+  displayName: z.string().min(1),
+  description: z.string(),
+  author: z.string(),
+  license: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  type: z.string().optional(),
+  version: z.string().optional(),
+  requires: z.object({
+    services: z.array(serviceRequirementSchema),
+    skills: z.array(slugString).optional().default([]),
+    extensions: z.array(slugString).optional().default([]),
+    registryDependencies: registryDependenciesSchema,
+  }),
+  input: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  output: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  config: z
+    .object({
+      schema: jsonSchemaObjectSchema,
+    })
+    .optional(),
+  execution: z
+    .object({
+      timeout: z.number().optional(),
+      outputRetries: z.number().min(0).max(5).optional(),
+    })
+    .optional(),
+});
+
+export type LocalFlowManifest = z.infer<typeof localFlowManifestSchema>;
+
+export function validateLocalFlowManifest(raw: unknown): {
+  valid: boolean;
+  errors: string[];
+  manifest?: unknown;
+} {
+  const result = localFlowManifestSchema.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 validateExtensionSource(source: string): ExtensionValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (source.trim().length === 0) {
+    return { valid: false, errors: ["Le contenu de l'extension est vide"], warnings };
+  }
+
+  if (!/export\s+default\b/.test(source)) {
+    errors.push(
+      "L'extension doit avoir un `export default function`. " +
+        "Exemple : export default function(pi: ExtensionAPI) { ... }",
+    );
+  }
+
+  if (!/\.registerTool\s*\(/.test(source)) {
+    warnings.push(
+      "L'extension n'appelle pas `pi.registerTool()`. " +
+        "Assurez-vous d'enregistrer au moins un outil.",
+    );
+  }
+
+  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(
+        "La signature `execute` n'a qu'un seul parametre. " +
+          "Le Pi SDK appelle execute(toolCallId, params, signal) — avec un seul parametre, " +
+          "votre fonction recevra le toolCallId (string) au lieu des params. " +
+          "Corrigez : execute(_toolCallId, params, signal) { ... }",
+      );
+      break;
+    }
+  }
+
+  if (executeMatches.length > 0 && !/content\s*:/.test(cleaned)) {
+    warnings.push(
+      "La fonction `execute` ne semble pas retourner `{ content: [...] }`. " +
+        'Le format attendu est : { content: [{ type: "text", text: "..." }] }',
+    );
+  }
+
+  let braceCount = 0;
+  for (const ch of cleaned) {
+    if (ch === "{") braceCount++;
+    else if (ch === "}") braceCount--;
+  }
+  if (braceCount !== 0) {
+    errors.push(
+      `Erreur de syntaxe probable : les accolades ne sont pas equilibrees (difference: ${braceCount})`,
+    );
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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,11 @@
+import { SLUG_REGEX } from "./index.ts";
+
+export { SLUG_REGEX };
+
+export function normalizeScope(scope: string): string {
+  return scope.startsWith("@") ? scope : `@${scope}`;
+}
+
+export function stripScope(scope: string): string {
+  return scope.startsWith("@") ? scope.slice(1) : scope;
+}

package/src/zip.ts

@@ -0,0 +1,190 @@
+import { unzipSync, zipSync, type Zippable } from "fflate";
+import { validateManifest, extractSkillMeta, validateExtensionSource } from "./index.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: Record<string, unknown>;
+  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 as Record<string, unknown>;
+
+  // Determine type (fallback "flow" for legacy manifests without type)
+  const type = (manifest.type as "flow" | "skill" | "extension") ?? "flow";
+
+  // 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 };
+}