aigpu 0.3.1

package/dist/cli/lib/examples/run.js

@@ -0,0 +1,71 @@
+import { examplesHelp } from "./help.js";
+import { createExamplesService } from "./service.js";
+import { LocalExamplesSource } from "./local-source.js";
+import { tokens } from "./search.js";
+import { pullExample } from "./pull.js";
+import { errorResult, usage } from "./errors.js";
+
+const SHA = /^[a-f0-9]{64}$/;
+const json = (value, pretty) => `${JSON.stringify(value, null, pretty ? 2 : 0)}\n`;
+
+function parse(command, args) {
+  const positional = [];
+  const options = {};
+  const allowed = {
+    search: new Set(["any", "limit", "revision", "pretty", "root"]),
+    show: new Set(["revision", "pretty", "root"]),
+    cat: new Set(["revision", "json", "root"]),
+    pull: new Set(["root", "out", "revision", "force", "pretty"]),
+  }[command];
+  if (!allowed) throw usage(`Unknown examples command: ${command}`);
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) { positional.push(argument); continue; }
+    const key = argument.slice(2);
+    if (!allowed.has(key) || Object.hasOwn(options, key)) throw usage(`Invalid or duplicate option: ${argument}`);
+    if (["limit", "revision", "out", "root"].includes(key)) {
+      if (!args[index + 1] || args[index + 1].startsWith("--")) throw usage(`Option ${argument} requires a value`);
+      options[key] = args[++index];
+    } else options[key] = true;
+  }
+  return { positional, options };
+}
+
+export async function runExamples(args, { env = process.env, platform = process.platform } = {}) {
+  try {
+    const [command, ...rest] = args;
+    if (command === undefined || command === "help" || command === "--help" || command === "-h") return { code: 0, stdout: examplesHelp };
+    const { positional, options } = parse(command, rest);
+    const counts = { search: 1, show: 1, cat: 2, pull: 1 };
+    if (positional.length !== counts[command]) throw usage(`Invalid arguments for examples ${command}`);
+    if (options.revision && !SHA.test(options.revision)) throw usage("--revision must be a lowercase SHA-256");
+    if (options.limit !== undefined && (!/^\d+$/.test(options.limit) || +options.limit < 1 || +options.limit > 100)) throw usage("--limit must be an integer from 1 to 100");
+    if (command === "pull" && !options.out) throw usage("pull requires --out <directory>");
+    if (command === "search" && !tokens(positional[0]).length) throw usage("Search query must contain a letter or number");
+
+    const source = new LocalExamplesSource({ root: options.root || env.AIGPU_EXAMPLES_DIR });
+    const common = { revision: options.revision, offline: true };
+    if (command === "pull") {
+      const state = await source.getIndex(common);
+      const manifest = await source.getManifest(state.index, positional[0]);
+      const result = await pullExample(source, manifest, options.out, { force: !!options.force, platform });
+      return { code: 0, stdout: json({ revision: manifest.revision, id: manifest.id, ...result, aggregateSha256: manifest.aggregateSha256 }, !!options.pretty) };
+    }
+
+    const examples = createExamplesService({ source, platform });
+    if (command === "search") {
+      const { operation: _operation, ...value } = await examples.execute({ operation: "search", query: positional[0], match: options.any ? "any" : "all", limit: options.limit ? +options.limit : 20, ...common });
+      return { code: 0, stdout: json(value, !!options.pretty) };
+    }
+    if (command === "show") {
+      const result = await examples.execute({ operation: "show", id: positional[0], ...common });
+      return { code: 0, stdout: json({ ...result.manifest }, !!options.pretty) };
+    }
+    const result = await examples.execute({ operation: "read", id: positional[0], path: positional[1], ...common });
+    if (!options.json) return { code: 0, stdout: Buffer.from(result.content) };
+    const { operation: _operation, contentType: _contentType, ...value } = result;
+    return { code: 0, stdout: json(value, false) };
+  } catch (error) {
+    return errorResult(error);
+  }
+}

package/dist/cli/lib/examples/search.js

@@ -0,0 +1,6 @@
+import { usage } from './errors.js';
+const aliases=new Map([['raymarching','raymarch'],['raymarched','raymarch'],['raymarch','raymarch']]);
+export function tokens(value){return value.normalize('NFKD').replace(/[\u0300-\u036f]/g,'').replace(/([a-z])([A-Z])/g,'$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(t=>aliases.get(t)??(t.endsWith('ing')?t.slice(0,-3):t.endsWith('ed')?t.slice(0,-2):t));}
+const has=(value,q)=>tokens(value).includes(q);
+function termScore(e,raw,q){let s=0;if(e.id===raw)s=Math.max(s,100);if(e.id.startsWith(raw)||has(e.id,q))s=Math.max(s,60);if(e.tags.some(x=>x===raw||has(x,q)))s=Math.max(s,50);if(has(e.title,q))s=Math.max(s,35);if(e.capabilities.some(x=>x===raw||has(x,q)))s=Math.max(s,25);if(has(e.description,q))s=Math.max(s,10);return s;}
+export function searchExamples(index,query,{any=false,limit=20}={}){const raw=tokens(query);if(!raw.length)throw usage('Search query must contain a letter or number');const originals=query.toLowerCase().split(/\s+/).filter(Boolean);return index.examples.map((e,order)=>{const scores=raw.map((q,i)=>termScore(e,originals[i]??q,q));return {e,order,scores,score:scores.reduce((a,b)=>a+b,0)}}).filter(x=>any?x.scores.some(Boolean):x.scores.every(Boolean)).sort((a,b)=>b.score-a.score||a.order-b.order||a.e.id.localeCompare(b.e.id)).slice(0,limit).map(({e,score})=>({...e,score}));}

package/dist/cli/lib/examples/service.js

@@ -0,0 +1,118 @@
+import { searchExamples } from "./search.js";
+import { lstat, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { destinationExists, filesystem, notFound, usage } from "./errors.js";
+import { assertSafeRelativePath } from "./paths.js";
+
+export function createExamplesService({
+  source,
+  downloadRoot = undefined,
+  platform = process.platform,
+  downloadExample = undefined,
+}) {
+  return {
+    async execute(input, { signal } = {}) {
+      signal?.throwIfAborted();
+      let downloadPath;
+      if (input.operation === "download") {
+        if (!downloadExample) throw usage("Example download is unavailable on this transport");
+        downloadPath = downloadDestination(downloadRoot, input.destination);
+        await assertNewDownloadDestination(downloadRoot, input.destination, downloadPath);
+      }
+      const request = { offline: input.offline === true, signal };
+      const state = await source.getIndex({ revision: input.revision, ...request });
+      signal?.throwIfAborted();
+      const offlineMetadata = state.offline && state.lastVerifiedAt
+        ? { lastVerifiedAt: state.lastVerifiedAt }
+        : {};
+      if (input.operation === "search") {
+        return {
+          operation: "search",
+          revision: state.index.revision,
+          results: searchExamples(state.index, input.query, {
+            any: input.match === "any",
+            limit: input.limit ?? 20,
+          }),
+          ...offlineMetadata,
+        };
+      }
+      if (!["show", "read", "download"].includes(input.operation)) {
+        throw new Error(`Unsupported examples operation: ${input.operation}`);
+      }
+      const manifest = await source.getManifest(state.index, input.id, request);
+      signal?.throwIfAborted();
+      if (input.operation === "show") {
+        return {
+          operation: "show",
+          manifest,
+          ...offlineMetadata,
+        };
+      }
+      if (input.operation === "read") {
+        const path = assertSafeRelativePath(input.path);
+        const file = manifest.files.find((candidate) => candidate.path === path);
+        if (!file) throw notFound(`File not found: ${path}`);
+        const bytes = await source.getFile(manifest, file, request);
+        signal?.throwIfAborted();
+        return {
+          operation: "read",
+          revision: manifest.revision,
+          id: manifest.id,
+          path: file.path,
+          contentType: file.contentType,
+          size: file.size,
+          sha256: file.sha256,
+          content: bytes.toString("utf8"),
+        };
+      }
+      const pulled = await downloadExample(source, manifest, downloadPath, { ...request, platform });
+      const { out, ...download } = pulled;
+      return {
+        operation: "download",
+        revision: manifest.revision,
+        id: manifest.id,
+        destination: await realpath(out),
+        ...download,
+        aggregateSha256: manifest.aggregateSha256,
+        ...offlineMetadata,
+      };
+    },
+  };
+}
+
+function downloadDestination(root, destination) {
+  if (typeof destination === "string" && (destination === ".." || destination.startsWith("../"))) {
+    throw usage("Download destination must stay inside the configured output directory");
+  }
+  if (typeof destination !== "string" || /[\p{Cc}\p{Cf}\p{Cs}]/u.test(destination)) {
+    throw usage("Download destination must be a safe relative path");
+  }
+  try {
+    assertSafeRelativePath(destination);
+  } catch {
+    throw usage("Download destination must be a safe relative path");
+  }
+  const resolvedRoot = resolve(root);
+  const resolvedDestination = resolve(resolvedRoot, destination);
+  const fromRoot = relative(resolvedRoot, resolvedDestination);
+  if (!fromRoot || fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot)) {
+    throw usage("Download destination must stay inside the configured output directory");
+  }
+  return resolvedDestination;
+}
+
+async function assertNewDownloadDestination(root, relativeDestination, destination) {
+  let candidate = resolve(root);
+  for (const part of relativeDestination.split("/")) {
+    candidate = resolve(candidate, part);
+    let status;
+    try {
+      status = await lstat(candidate);
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      throw filesystem(`Cannot inspect download destination: ${error.message}`);
+    }
+    if (status.isSymbolicLink()) throw filesystem("Download destination must not traverse a symbolic link");
+  }
+  throw destinationExists(`Destination already exists: ${destination}`);
+}