@appstrate/validation 1.0.1 → 1.1.0

package/README.md

@@ -1 +1,165 @@
-# validation
+# @appstrate/validation
+
+Shared validation library for the Appstrate ecosystem. Provides manifest schemas (Zod), package ZIP parsing, naming helpers, dependency extraction, and integrity hashing — used by both the [Appstrate platform](https://github.com/appstrate/strate) and the [Appstrate [registry]](https://github.com/appstrate/registry).
+
+## Installation
+
+```sh
+# From npm
+bun add @appstrate/validation
+```
+
+## Exports
+
+The package exposes five entry points:
+
+| Import path                          | Description                                           |
+| ------------------------------------ | ----------------------------------------------------- |
+| `@appstrate/validation`              | Manifest schemas, validators, skill/extension helpers |
+| `@appstrate/validation/zip`          | ZIP parsing, artifact creation, package extraction    |
+| `@appstrate/validation/naming`       | Scoped name helpers, slug regex, packageId conversion |
+| `@appstrate/validation/dependencies` | Registry dependency extraction from manifests         |
+| `@appstrate/validation/integrity`    | SHA256 integrity hash computation                     |
+
+## Usage
+
+### Manifest Validation
+
+```ts
+import { validateManifest, baseManifestSchema, flowManifestSchema } from "@appstrate/validation";
+
+// Validate any manifest (auto-dispatches by type)
+const result = validateManifest(rawJson);
+if (result.valid) {
+  console.log(result.manifest); // typed BaseManifest | FlowManifest
+} else {
+  console.error(result.errors); // string[]
+}
+```
+
+Three manifest schemas are available:
+
+- **`baseManifestSchema`** — Common fields for all types: `name` (`@scope/package-name`), `version` (semver), `type` (`flow` | `skill` | `extension`), optional `description`, `keywords`, `license`, `registryDependencies`
+- **`flowManifestSchema`** — Extends base with flow-specific fields: `schemaVersion`, `displayName`, `author`, `requires` (services, skills, extensions), `input`/`output`/`config` schemas, `execution` options
+- **`localFlowManifestSchema`** — Relaxed schema for strate built-in flows (slug name instead of scoped, optional version)
+
+### Skill & Extension Validation
+
+```ts
+import { extractSkillMeta, validateExtensionSource } from "@appstrate/validation";
+
+// Extract YAML frontmatter from SKILL.md
+const meta = extractSkillMeta(skillMdContent);
+// { name: "my-skill", description: "...", warnings: [] }
+
+// Validate TypeScript extension source
+const result = validateExtensionSource(tsSource);
+// { valid: true, errors: [], warnings: [] }
+```
+
+### ZIP Parsing
+
+```ts
+import { parsePackageZip, PackageZipError } from "@appstrate/validation/zip";
+
+try {
+  const parsed = parsePackageZip(zipBuffer);
+  // { manifest, content, files, type }
+} catch (err) {
+  if (err instanceof PackageZipError) {
+    console.error(err.code, err.message);
+    // Codes: FILE_TOO_LARGE, ZIP_INVALID, ZIP_BOMB, MISSING_MANIFEST,
+    //        INVALID_MANIFEST, MISSING_CONTENT, INVALID_CONTENT
+  }
+}
+```
+
+Lower-level ZIP utilities:
+
+- **`zipArtifact(entries, level?)`** — Create a ZIP from file entries
+- **`unzipArtifact(buffer)`** — Decompress with path sanitization (filters `..`, `__MACOSX`, absolute paths)
+- **`detectFolderWrapper(entries)`** — Detect single-folder wrapping in ZIP
+
+### Naming Helpers
+
+```ts
+import {
+  SLUG_REGEX,
+  normalizeScope,
+  stripScope,
+  scopedNameToPackageId,
+  packageIdToScopedName,
+  depEntryToPackageId,
+} from "@appstrate/validation/naming";
+
+normalizeScope("myscope"); // "@myscope"
+stripScope("@myscope"); // "myscope"
+scopedNameToPackageId("@scope/name"); // "scope--name"
+packageIdToScopedName("scope--name"); // "@scope/name"
+packageIdToScopedName("local-slug"); // null
+depEntryToPackageId("@scope", "name"); // "scope--name"
+```
+
+### Dependency Extraction
+
+```ts
+import { extractDependencies } from "@appstrate/validation/dependencies";
+import type { DepEntry } from "@appstrate/validation/dependencies";
+
+const deps: DepEntry[] = extractDependencies(manifest);
+// [{ depScope: "@scope", depName: "tool", depType: "skill", versionRange: "^1.0.0" }]
+```
+
+### Integrity
+
+```ts
+import { computeIntegrity } from "@appstrate/validation/integrity";
+
+const sri = computeIntegrity(zipBuffer);
+// "sha256-abc123..."
+```
+
+## Project Structure
+
+```
+@appstrate/validation/
+├── src/
+│   ├── index.ts          # Manifest schemas (Zod), validateManifest, extractSkillMeta, validateExtensionSource
+│   ├── zip.ts            # ZIP parse/create, parsePackageZip, PackageZipError
+│   ├── naming.ts         # SLUG_REGEX, normalizeScope, stripScope, scopedNameToPackageId, packageIdToScopedName
+│   ├── dependencies.ts   # extractDependencies, DepEntry type
+│   └── integrity.ts      # computeIntegrity (SHA256 SRI hash)
+│
+├── tests/                # bun:test (63 tests across 5 files)
+│   ├── index.test.ts     # Manifest validation (flow, skill, extension, base)
+│   ├── zip.test.ts       # ZIP parsing, folder detection, error codes, security
+│   ├── naming.test.ts    # Naming helpers, packageId conversion
+│   ├── dependencies.test.ts # Dependency extraction from manifests
+│   └── integrity.test.ts # SHA256 integrity computation
+│
+├── package.json
+├── tsconfig.json
+└── eslint.config.js
+```
+
+## Development
+
+```sh
+bun test             # Run all tests (63 tests, 5 files)
+bun run check        # TypeScript type-check + ESLint + Prettier
+bun run lint         # ESLint only
+bun run format       # Prettier format
+```
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Validation**: Zod 4
+- **Semver**: semver (range validation, version parsing)
+- **ZIP**: fflate (compression/decompression)
+- **Testing**: bun:test (built-in)
+- **Code quality**: ESLint + Prettier + TypeScript strict mode
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appstrate/validation",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "type": "module",
   "files": ["src"],
   "exports": {

package/src/dependencies.ts

@@ -6,20 +6,18 @@ export interface DepEntry {
 }
 
 export function extractDependencies(manifest: Record<string, unknown>): DepEntry[] {
-  const requires = manifest.requires as
+  const registryDependencies = manifest.registryDependencies as
     | {
-        registryDependencies?: {
-          skills?: Record<string, string>;
-          extensions?: Record<string, string>;
-        };
+        skills?: Record<string, string>;
+        extensions?: Record<string, string>;
       }
     | undefined;
 
-  if (!requires?.registryDependencies) return [];
+  if (!registryDependencies) return [];
 
   const deps: DepEntry[] = [];
 
-  const { skills = {}, extensions = {} } = requires.registryDependencies;
+  const { skills = {}, extensions = {} } = registryDependencies;
 
   for (const [fullName, versionRange] of Object.entries(skills)) {
     const { scope, name } = parseScopedName(fullName);
@@ -35,9 +33,11 @@ export function extractDependencies(manifest: Record<string, unknown>): DepEntry
 }
 
 function parseScopedName(fullName: string): { scope: string; name: string } {
-  const match = fullName.match(/^(@[a-z0-9-]+)\/([a-z0-9-]+)$/);
+  const match = fullName.match(
+    /^(@[a-z0-9]([a-z0-9-]*[a-z0-9])?)\/([a-z0-9]([a-z0-9-]*[a-z0-9])?)$/,
+  );
   if (!match) {
     throw new Error(`Invalid scoped package name: ${fullName}`);
   }
-  return { scope: match[1]!, name: match[2]! };
+  return { scope: match[1]!, name: match[3]! };
 }

package/src/index.ts

@@ -6,7 +6,7 @@ export { SLUG_REGEX };
 
 const flowFieldTypeEnum = z.enum(["string", "number", "boolean", "array", "object", "file"]);
 
-const jsonSchemaPropertySchema = z.object({
+export const jsonSchemaPropertySchema = z.object({
   type: flowFieldTypeEnum,
   description: z.string().optional(),
   default: z.unknown().optional(),
@@ -19,16 +19,16 @@ const jsonSchemaPropertySchema = z.object({
   maxFiles: z.number().int().positive().optional(),
 });
 
-const jsonSchemaObjectSchema = z.object({
+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(),
 });
 
-const serviceRequirementSchema = z.object({
+export 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)",
+    error: "Must be a valid slug (a-z, 0-9, hyphens, no leading/trailing hyphen)",
   }),
   provider: z.string(),
   scopes: z.array(z.string()).optional().default([]),
@@ -36,7 +36,7 @@ const serviceRequirementSchema = z.object({
 });
 
 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)",
+  error: "Must be a valid slug (a-z, 0-9, hyphens, no leading/trailing hyphen)",
 });
 
 const semverRangeString = z.string().refine((val) => semver.validRange(val) !== null, {
@@ -54,8 +54,9 @@ const registryDependenciesSchema = z
 // 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 scopedNameRegex = /^@[a-z0-9]([a-z0-9-]*[a-z0-9])?\/[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+export const packageTypeEnum = z.enum(["flow", "skill", "extension"]);
+export type PackageType = z.infer<typeof packageTypeEnum>;
 
 export const baseManifestSchema = z.object({
   name: z.string().regex(scopedNameRegex, { error: "Must follow the format @scope/package-name" }),
@@ -73,6 +74,12 @@ export const baseManifestSchema = z.object({
 
 export type BaseManifest = z.infer<typeof baseManifestSchema>;
 
+// ─── 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 — used by both flowManifestSchema and localFlowManifestSchema
 // ─────────────────────────────────────────────
@@ -82,7 +89,6 @@ const flowSharedFields = {
     services: z.array(serviceRequirementSchema),
     skills: z.array(slugString).optional().default([]),
     extensions: z.array(slugString).optional().default([]),
-    registryDependencies: registryDependenciesSchema,
   }),
   input: z
     .object({
@@ -122,10 +128,6 @@ export const flowManifestSchema = baseManifestSchema.extend({
 
 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
 // ─────────────────────────────────────────────
@@ -185,7 +187,7 @@ export function extractSkillMeta(content: string): {
   const warnings: string[] = [];
   const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
   if (!fmMatch) {
-    warnings.push("Pas de frontmatter YAML detecte (bloc --- ... --- attendu)");
+    warnings.push("No YAML frontmatter detected (expected --- ... --- block)");
     return { name: "", description: "", warnings };
   }
 
@@ -197,10 +199,10 @@ export function extractSkillMeta(content: string): {
   const description = descMatch ? stripQuotes(descMatch[1]!) : "";
 
   if (!name) {
-    warnings.push("Champ 'name' manquant dans le frontmatter YAML");
+    warnings.push("Missing 'name' field in YAML frontmatter");
   }
   if (!description) {
-    warnings.push("Champ 'description' manquant dans le frontmatter YAML");
+    warnings.push("Missing 'description' field in YAML frontmatter");
   }
 
   return { name, description, warnings };
@@ -268,20 +270,19 @@ export function validateExtensionSource(source: string): ExtensionValidationResu
   const warnings: string[] = [];
 
   if (source.trim().length === 0) {
-    return { valid: false, errors: ["Le contenu de l'extension est vide"], warnings };
+    return { valid: false, errors: ["Extension content is empty"], warnings };
   }
 
   if (!/export\s+default\b/.test(source)) {
     errors.push(
-      "L'extension doit avoir un `export default function`. " +
-        "Exemple : export default function(pi: ExtensionAPI) { ... }",
+      "Extension must have an `export default function`. " +
+        "Example: 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.",
+      "Extension does not call `pi.registerTool()`. " + "Make sure to register at least one tool.",
     );
   }
 
@@ -292,10 +293,10 @@ export function validateExtensionSource(source: string): ExtensionValidationResu
     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) { ... }",
+        "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;
     }
@@ -303,8 +304,8 @@ export function validateExtensionSource(source: string): ExtensionValidationResu
 
   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: "..." }] }',
+      "The `execute` function does not seem to return `{ content: [...] }`. " +
+        'Expected format: { content: [{ type: "text", text: "..." }] }',
     );
   }
 
@@ -314,9 +315,7 @@ export function validateExtensionSource(source: string): ExtensionValidationResu
     else if (ch === "}") braceCount--;
   }
   if (braceCount !== 0) {
-    errors.push(
-      `Erreur de syntaxe probable : les accolades ne sont pas equilibrees (difference: ${braceCount})`,
-    );
+    errors.push(`Probable syntax error: braces are not balanced (difference: ${braceCount})`);
   }
 
   return { valid: errors.length === 0, errors, warnings };

package/src/naming.ts

@@ -8,3 +8,25 @@ export function normalizeScope(scope: string): string {
 export function stripScope(scope: string): string {
   return scope.startsWith("@") ? scope.slice(1) : scope;
 }
+
+/** Convert "@scope/name" to strate packageId "scope--name" */
+export function scopedNameToPackageId(scopedName: string): string {
+  const match = scopedName.match(/^@([a-z0-9][a-z0-9-]*[a-z0-9]?)\/([a-z0-9][a-z0-9-]*[a-z0-9]?)$/);
+  if (!match) throw new Error(`Invalid scoped package name: ${scopedName}`);
+  return `${match[1]}--${match[2]}`;
+}
+
+/** Convert strate packageId "scope--name" to "@scope/name", or null for local slugs */
+export function packageIdToScopedName(packageId: string): string | null {
+  const idx = packageId.indexOf("--");
+  if (idx === -1) return null;
+  const scope = packageId.slice(0, idx);
+  const name = packageId.slice(idx + 2);
+  if (!scope || !name) return null;
+  return `@${scope}/${name}`;
+}
+
+/** Convert separated scope + name to strate packageId */
+export function depEntryToPackageId(depScope: string, depName: string): string {
+  return `${stripScope(depScope)}--${depName}`;
+}