@unicity-astrid/sdk 0.1.0

package/src/elicit.ts

@@ -0,0 +1,136 @@
+/**
+ * Interactive user input during install/upgrade. Mirrors `astrid_sdk::elicit`.
+ *
+ * These functions are only callable from `@install` / `@upgrade` lifecycle
+ * methods; calling them from a tool or interceptor returns `not-in-lifecycle`.
+ * The host blocks the WASM thread until the frontend collects input or the
+ * request times out (120s).
+ *
+ * Post per-domain WIT split, the host returns a typed `elicit-response`
+ * variant directly. We unpack it into the language-natural shape: `text` /
+ * `textWithDefault` / `select` return strings; `array` returns string[];
+ * `secret` returns void (the value never leaves the SecretStore).
+ */
+
+import {
+  elicit as hostElicit,
+  hasSecret as hostHasSecret,
+  type ElicitResponse,
+} from "astrid:elicit/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+
+function validateKey(key: string): void {
+  if (key.trim() === "") {
+    throw SysError.api("elicit key must not be empty");
+  }
+}
+
+/**
+ * Store a secret via the kernel's SecretStore. The capsule NEVER receives
+ * the value back — verify via {@link hasSecret} and dereference at runtime
+ * by name.
+ */
+export function secret(key: string, description: string): void {
+  validateKey(key);
+  const resp = callHost(`elicit.secret(${JSON.stringify(key)})`, () =>
+    hostElicit({
+      kind: "secret",
+      key,
+      description,
+      options: undefined,
+      defaultValue: undefined,
+    }),
+  );
+  if (resp.tag !== "secret-stored") {
+    throw SysError.api(
+      `elicit.secret: expected 'secret-stored' response, got '${resp.tag}'`,
+    );
+  }
+}
+
+/** Check whether a secret with this key was previously stored. */
+export function hasSecret(key: string): boolean {
+  validateKey(key);
+  return callHost(`elicit.hasSecret(${JSON.stringify(key)})`, () => hostHasSecret(key));
+}
+
+/** Prompt the user for a text value. */
+export function text(key: string, description: string): string {
+  return elicitText(key, description, undefined);
+}
+
+/** Prompt with a pre-filled default. */
+export function textWithDefault(
+  key: string,
+  description: string,
+  defaultValue: string,
+): string {
+  return elicitText(key, description, defaultValue);
+}
+
+/** Prompt for a selection from a list. */
+export function select(key: string, description: string, options: string[]): string {
+  validateKey(key);
+  if (options.length === 0) {
+    throw SysError.api("elicit.select requires at least one option");
+  }
+  const resp = callHost(`elicit.select(${JSON.stringify(key)})`, () =>
+    hostElicit({
+      kind: "select",
+      key,
+      description,
+      options,
+      defaultValue: undefined,
+    }),
+  );
+  const value = expectValue("elicit.select", resp);
+  if (options.indexOf(value) < 0) {
+    throw SysError.api(
+      `host returned value not in provided options: ${value.slice(0, 64)}`,
+    );
+  }
+  return value;
+}
+
+/** Prompt for multiple text values. */
+export function array(key: string, description: string): string[] {
+  validateKey(key);
+  const resp = callHost(`elicit.array(${JSON.stringify(key)})`, () =>
+    hostElicit({
+      kind: "array",
+      key,
+      description,
+      options: undefined,
+      defaultValue: undefined,
+    }),
+  );
+  if (resp.tag !== "values") {
+    throw SysError.api(`elicit.array: expected 'values' response, got '${resp.tag}'`);
+  }
+  return resp.val;
+}
+
+function elicitText(
+  key: string,
+  description: string,
+  defaultValue: string | undefined,
+): string {
+  validateKey(key);
+  const resp = callHost(`elicit.text(${JSON.stringify(key)})`, () =>
+    hostElicit({
+      kind: "text",
+      key,
+      description,
+      options: undefined,
+      defaultValue,
+    }),
+  );
+  return expectValue("elicit.text", resp);
+}
+
+function expectValue(label: string, resp: ElicitResponse): string {
+  if (resp.tag !== "value") {
+    throw SysError.api(`${label}: expected 'value' response, got '${resp.tag}'`);
+  }
+  return resp.val;
+}

package/src/env.ts

@@ -0,0 +1,31 @@
+/**
+ * Capsule configuration — Astrid's equivalent of environment variables.
+ * Mirrors `astrid_sdk::env`. Values are injected by the kernel at load time
+ * from `Capsule.toml [env]` entries.
+ *
+ * Per the per-domain WIT split, `get-config` now returns `option<string>` so
+ * the caller can distinguish "key not set" from "key explicitly set to empty
+ * string". The wrapper preserves that distinction via {@link tryGet}; {@link get}
+ * collapses `none` to `""` for the std::env::var-style ergonomic case.
+ */
+
+import { getConfig } from "astrid:sys/host@1.0.0";
+import { callHost } from "./errors.js";
+
+/** Well-known config key carrying the kernel's Unix domain socket path. */
+export const CONFIG_SOCKET_PATH = "ASTRID_SOCKET_PATH";
+
+/** Read a config value. Returns `""` if the key is not set. */
+export function get(key: string): string {
+  return tryGet(key) ?? "";
+}
+
+/** Read a config value or `undefined` if not set. */
+export function tryGet(key: string): string | undefined {
+  return callHost(`env.get(${JSON.stringify(key)})`, () => getConfig(key));
+}
+
+/** Read a config value as bytes. */
+export function getBytes(key: string): Uint8Array {
+  return new TextEncoder().encode(get(key));
+}

package/src/errors.ts

@@ -0,0 +1,122 @@
+/**
+ * Unified error type for SDK operations. Mirrors `astrid_sdk::SysError` but
+ * uses idiomatic JS throw/catch instead of `Result<T, E>`.
+ *
+ * Post per-domain-WIT migration, every fallible host call returns a typed
+ * `result<T, error-code>` where `error-code` is a domain-specific variant
+ * (e.g. `astrid:fs/host.error-code`, `astrid:ipc/host.error-code`).
+ * ComponentizeJS rejects with `{ tag, val? }` objects on the error arm. We
+ * preserve the variant tag on `SysError.code` so downstream code can branch
+ * on `if (err.code === "quota") ...` without losing the typed kind. The
+ * raw payload (the unpacked variant value, if any) survives on `err.payload`
+ * for the few callers that need it.
+ *
+ * The three legacy origin tags — `HostError`, `JsonError`, `ApiError` —
+ * remain on `SysError.kind` for source compatibility. Code that previously
+ * checked `err.code` for "HostError" should migrate to `err.kind` because
+ * `err.code` now carries the WIT variant tag.
+ */
+
+export type SysErrorKind = "HostError" | "JsonError" | "ApiError";
+
+export class SysError extends Error {
+  override readonly name = "SysError";
+  /** Legacy classification: where the error originated. */
+  readonly kind: SysErrorKind;
+  /** Typed WIT variant tag (e.g. "quota", "capability-denied", "timeout").
+   *  `undefined` for SDK-internal errors that didn't come from the host. */
+  readonly code: string | undefined;
+  /** Raw unpacked WIT variant payload, when present. */
+  readonly payload: unknown;
+
+  constructor(
+    kind: SysErrorKind,
+    message: string,
+    options?: ErrorOptions & { code?: string; payload?: unknown },
+  ) {
+    super(`[${kind}${options?.code ? `:${options.code}` : ""}] ${message}`, options);
+    this.kind = kind;
+    this.code = options?.code;
+    this.payload = options?.payload;
+  }
+
+  static host(
+    message: string,
+    cause?: unknown,
+    code?: string,
+    payload?: unknown,
+  ): SysError {
+    const opts: ErrorOptions & { code?: string; payload?: unknown } = {};
+    if (cause !== undefined) opts.cause = cause;
+    if (code !== undefined) opts.code = code;
+    if (payload !== undefined) opts.payload = payload;
+    return new SysError("HostError", message, opts);
+  }
+
+  static json(message: string, cause?: unknown): SysError {
+    return new SysError("JsonError", message, cause === undefined ? undefined : { cause });
+  }
+
+  static api(message: string, cause?: unknown): SysError {
+    return new SysError("ApiError", message, cause === undefined ? undefined : { cause });
+  }
+}
+
+/**
+ * Wraps a synchronous host call, normalizing any thrown value into a
+ * `SysError`. After the per-domain WIT split, host imports throw
+ * `{ tag, val? }` objects representing the typed error-code variant.
+ * We unpack the tag onto `SysError.code` so capsule authors can branch
+ * on the WIT variant by name. The raw payload (the unpacked `val`, if any)
+ * survives on `SysError.payload` for callers that need it.
+ */
+export function callHost<T>(label: string, fn: () => T): T {
+  try {
+    return fn();
+  } catch (raw) {
+    if (raw instanceof SysError) throw raw;
+    const wit = extractWitError(raw);
+    if (wit !== undefined) {
+      throw SysError.host(`${label}: ${wit.message}`, raw, wit.code, wit.payload);
+    }
+    const message = typeof raw === "string" ? raw : (raw as Error)?.message ?? String(raw);
+    throw SysError.host(`${label}: ${message}`, raw);
+  }
+}
+
+interface WitErrorView {
+  code: string;
+  message: string;
+  payload: unknown;
+}
+
+/**
+ * Componentize-js rejects fallible host calls with `{ tag, val? }` shapes
+ * (the unpacked variant of `result<T, error-code>`). Strings or numbers
+ * occasionally surface for trap-style failures. This helper produces a
+ * uniform view of the variant for `callHost` to convert into `SysError`.
+ */
+function extractWitError(raw: unknown): WitErrorView | undefined {
+  if (raw === null || typeof raw !== "object") return undefined;
+  const r = raw as Record<string, unknown>;
+  if (typeof r["tag"] !== "string") return undefined;
+  const code = r["tag"];
+  const val = r["val"];
+  let message: string;
+  if (typeof val === "string") {
+    message = `${code}: ${val}`;
+  } else if (val === undefined) {
+    message = code;
+  } else {
+    message = `${code}: ${safeStringify(val)}`;
+  }
+  return { code, message, payload: val };
+}
+
+function safeStringify(v: unknown): string {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return String(v);
+  }
+}

package/src/fs.ts

@@ -0,0 +1,357 @@
+/**
+ * Virtual filesystem — shape-compatible with `node:fs/promises` where it
+ * makes sense, including a `Stats`-like object with `isFile()` /
+ * `isDirectory()` methods.
+ *
+ * Path schemes follow VFS conventions (`workspace://`, `home://`, `tmp://`).
+ * The kernel re-resolves and re-validates every path on every call;
+ * {@link canonicalize} is for display / equality only, NOT a security check
+ * that subsequent calls can rely on.
+ *
+ * The Rust SDK's surface is sync (`std::fs`); we expose async (`await`) to
+ * match Node idioms even though the underlying host calls are synchronous.
+ * StarlingMonkey syncifies awaits at the WASM boundary.
+ */
+
+import {
+  fsOpen as hostOpen,
+  fsExists as hostExists,
+  fsMkdir as hostMkdir,
+  fsMkdirAll as hostMkdirAll,
+  fsReaddir as hostReaddir,
+  fsStat as hostStat,
+  fsStatSymlink as hostStatSymlink,
+  fsUnlink as hostUnlink,
+  readFile as hostReadFile,
+  writeFile as hostWriteFile,
+  fsAppend as hostAppend,
+  fsCopy as hostCopy,
+  fsRename as hostRename,
+  fsRemoveDirAll as hostRemoveDirAll,
+  fsCanonicalize as hostCanonicalize,
+  fsReadLink as hostReadLink,
+  fsHardLink as hostHardLink,
+  type FileStat,
+  type FileHandle as WitFileHandle,
+  type OpenMode,
+  type FileType,
+} from "astrid:fs/host@1.0.0";
+import { SysError, callHost } from "./errors.js";
+
+const decoder = new TextDecoder();
+const encoder = new TextEncoder();
+
+export type { OpenMode, FileType } from "astrid:fs/host@1.0.0";
+
+/**
+ * Stat result. Shaped like Node's `fs.Stats` for the fields the Astrid VFS
+ * surfaces. `size` is `bigint` (WIT `u64`); use `Number(size)` if you need a
+ * regular number and you're sure it fits.
+ */
+export class Stats {
+  readonly size: bigint;
+  readonly mode: number;
+  readonly kind: FileType;
+  readonly mtimeMs: number | undefined;
+  readonly birthtimeMs: number | undefined;
+  readonly atimeMs: number | undefined;
+
+  constructor(stat: FileStat) {
+    this.size = stat.size;
+    this.mode = stat.mode;
+    this.kind = stat.kind;
+    this.mtimeMs = datetimeToMs(stat.modified);
+    this.birthtimeMs = datetimeToMs(stat.created);
+    this.atimeMs = datetimeToMs(stat.accessed);
+  }
+
+  isFile(): boolean {
+    return this.kind === "regular";
+  }
+
+  isDirectory(): boolean {
+    return this.kind === "directory";
+  }
+
+  isSymbolicLink(): boolean {
+    return this.kind === "symlink";
+  }
+
+  isEmpty(): boolean {
+    return this.size === 0n;
+  }
+}
+
+/** Directory entry returned by `readdir({ withFileTypes: true })`. */
+export class Dirent {
+  readonly name: string;
+  readonly path: string;
+  readonly parentPath: string;
+
+  constructor(parentPath: string, name: string) {
+    this.name = name;
+    this.parentPath = parentPath;
+    this.path = parentPath.endsWith("/") ? parentPath + name : `${parentPath}/${name}`;
+  }
+}
+
+/**
+ * Open file handle. Returned from {@link open}. The host releases the
+ * underlying file descriptor automatically when the handle is dropped via
+ * `Symbol.dispose` or `.close()`. Per-capsule cap: 16 open file handles.
+ *
+ * ```ts
+ * using f = await fs.open("workspace://data.bin", "read-write");
+ * await f.writeAt(0n, new TextEncoder().encode("hello"));
+ * ```
+ */
+export class FileHandle {
+  #inner: WitFileHandle | undefined;
+  readonly path: string;
+
+  constructor(inner: WitFileHandle, path: string) {
+    this.#inner = inner;
+    this.path = path;
+  }
+
+  /** Read up to `maxBytes` from `offset`. Empty result signals EOF at that offset. */
+  async readAt(offset: bigint, maxBytes: number): Promise<Uint8Array> {
+    return callHost(`fs.FileHandle.readAt(${quote(this.path)})`, () =>
+      this.#requireInner().readAt(offset, maxBytes),
+    );
+  }
+
+  /** Write `data` at `offset`. Returns bytes actually written. */
+  async writeAt(offset: bigint, data: Uint8Array): Promise<number> {
+    return callHost(`fs.FileHandle.writeAt(${quote(this.path)})`, () =>
+      this.#requireInner().writeAt(offset, data),
+    );
+  }
+
+  /** Flush buffered data (only) to disk — `fdatasync(2)`. */
+  async syncData(): Promise<void> {
+    callHost(`fs.FileHandle.syncData(${quote(this.path)})`, () =>
+      this.#requireInner().syncData(),
+    );
+  }
+
+  /** Flush both data and metadata to disk — `fsync(2)`. */
+  async syncAll(): Promise<void> {
+    callHost(`fs.FileHandle.syncAll(${quote(this.path)})`, () =>
+      this.#requireInner().syncAll(),
+    );
+  }
+
+  /** Race-free counterpart to {@link stat} on the path. */
+  async stat(): Promise<Stats> {
+    const raw = callHost(`fs.FileHandle.stat(${quote(this.path)})`, () =>
+      this.#requireInner().stat(),
+    );
+    return new Stats(raw);
+  }
+
+  /** Truncate or extend the file to `size` bytes. Extending past end fills with zeros. */
+  async setLen(size: bigint): Promise<void> {
+    callHost(`fs.FileHandle.setLen(${quote(this.path)})`, () =>
+      this.#requireInner().setLen(size),
+    );
+  }
+
+  close(): void {
+    if (this.#inner === undefined) return;
+    const inner = this.#inner;
+    this.#inner = undefined;
+    try {
+      inner[Symbol.dispose]();
+    } catch {
+      // Already disposed by the runtime; safe to ignore.
+    }
+  }
+
+  [Symbol.dispose](): void {
+    this.close();
+  }
+
+  #requireInner(): WitFileHandle {
+    if (this.#inner === undefined) {
+      throw SysError.api(`FileHandle ${quote(this.path)} is closed`);
+    }
+    return this.#inner;
+  }
+}
+
+export interface ReadFileOptions {
+  /** When set, decode bytes as a string with this encoding. */
+  encoding?: "utf8";
+}
+
+export interface ReaddirOptions {
+  /** When true, yields `Dirent` objects instead of bare name strings. */
+  withFileTypes?: boolean;
+}
+
+/** Open a file by path. Required capability depends on `mode`. */
+export async function open(path: string, mode: OpenMode): Promise<FileHandle> {
+  const inner = callHost(`fs.open(${quote(path)})`, () => hostOpen(path, mode));
+  return new FileHandle(inner, path);
+}
+
+export async function exists(path: string): Promise<boolean> {
+  return callHost(`fs.exists(${quote(path)})`, () => hostExists(path));
+}
+
+export async function stat(path: string): Promise<Stats> {
+  const raw = callHost(`fs.stat(${quote(path)})`, () => hostStat(path));
+  return new Stats(raw);
+}
+
+/** Stat without following symlinks — `lstat(2)`. */
+export async function lstat(path: string): Promise<Stats> {
+  const raw = callHost(`fs.lstat(${quote(path)})`, () => hostStatSymlink(path));
+  return new Stats(raw);
+}
+
+export async function readFile(
+  path: string,
+  options?: ReadFileOptions,
+): Promise<Uint8Array | string> {
+  const bytes = callHost(`fs.readFile(${quote(path)})`, () => hostReadFile(path));
+  if (options?.encoding === "utf8") return decoder.decode(bytes);
+  return bytes;
+}
+
+/** Read a file as UTF-8 text. */
+export async function readTextFile(path: string): Promise<string> {
+  const bytes = callHost(`fs.readTextFile(${quote(path)})`, () => hostReadFile(path));
+  try {
+    return decoder.decode(bytes);
+  } catch (err) {
+    throw SysError.api(`fs.readTextFile(${quote(path)}): ${(err as Error).message}`, err);
+  }
+}
+
+export async function writeFile(path: string, data: string | Uint8Array): Promise<void> {
+  const bytes = typeof data === "string" ? encoder.encode(data) : data;
+  callHost(`fs.writeFile(${quote(path)})`, () => hostWriteFile(path, bytes));
+}
+
+/** Append `data` to a file, creating it if absent. */
+export async function appendFile(path: string, data: string | Uint8Array): Promise<void> {
+  const bytes = typeof data === "string" ? encoder.encode(data) : data;
+  callHost(`fs.appendFile(${quote(path)})`, () => hostAppend(path, bytes));
+}
+
+/**
+ * Create a directory. Mirrors `std::fs::create_dir` / `mkdir(2)` — strict.
+ * Fails with `already-exists` if the path exists. Use {@link mkdirAll} for
+ * idempotent "ensure-exists" semantics.
+ */
+export async function mkdir(path: string): Promise<void> {
+  callHost(`fs.mkdir(${quote(path)})`, () => hostMkdir(path));
+}
+
+/** Create a directory and all missing parents. Idempotent. */
+export async function mkdirAll(path: string): Promise<void> {
+  callHost(`fs.mkdirAll(${quote(path)})`, () => hostMkdirAll(path));
+}
+
+/** Remove a file. Mirrors `fs.unlink` / `fs.rm` (file-only). */
+export async function rm(path: string): Promise<void> {
+  callHost(`fs.rm(${quote(path)})`, () => hostUnlink(path));
+}
+
+/** Alias for {@link rm} matching Node's `fs.unlink`. */
+export const unlink = rm;
+
+/**
+ * Remove a directory and all its contents recursively. Refuses to traverse
+ * symlinks to prevent sandbox escapes. Returns the count of removed entries.
+ */
+export async function removeDirAll(path: string): Promise<bigint> {
+  return callHost(`fs.removeDirAll(${quote(path)})`, () => hostRemoveDirAll(path));
+}
+
+/** Copy a file from `src` to `dst`. Overwrites `dst`. */
+export async function copy(src: string, dst: string): Promise<void> {
+  callHost(`fs.copy(${quote(src)} -> ${quote(dst)})`, () => hostCopy(src, dst));
+}
+
+/** Rename (move) within the same VFS scheme. Cross-scheme returns `cross-vfs`. */
+export async function rename(src: string, dst: string): Promise<void> {
+  callHost(`fs.rename(${quote(src)} -> ${quote(dst)})`, () => hostRename(src, dst));
+}
+
+/**
+ * Resolve a path to its canonical form, following symlinks. Returns a
+ * VFS-scheme path, never a host real-path. NOT a TOCTOU-safe security check.
+ */
+export async function canonicalize(path: string): Promise<string> {
+  return callHost(`fs.canonicalize(${quote(path)})`, () => hostCanonicalize(path));
+}
+
+/** Read a symlink target without following it. */
+export async function readLink(path: string): Promise<string> {
+  return callHost(`fs.readLink(${quote(path)})`, () => hostReadLink(path));
+}
+
+/** Create a hard link. Both endpoints must be in the same VFS scheme. */
+export async function hardLink(src: string, linkPath: string): Promise<void> {
+  callHost(`fs.hardLink(${quote(src)} -> ${quote(linkPath)})`, () =>
+    hostHardLink(src, linkPath),
+  );
+}
+
+/**
+ * Read directory entries. Returns string[] by default to match
+ * `fs.readdir(path)`; pass `{ withFileTypes: true }` for `Dirent[]`.
+ */
+export async function readdir(path: string): Promise<string[]>;
+export async function readdir(
+  path: string,
+  options: { withFileTypes: true },
+): Promise<Dirent[]>;
+export async function readdir(
+  path: string,
+  options?: ReaddirOptions,
+): Promise<string[] | Dirent[]> {
+  const names = callHost(`fs.readdir(${quote(path)})`, () => hostReaddir(path));
+  if (options?.withFileTypes) {
+    return names.map((n) => new Dirent(path, n));
+  }
+  return names;
+}
+
+/**
+ * Stream-style directory iteration. Mirrors `fs.opendir` / `Dir`. The VFS
+ * resolves all entries in one host call, so the async-iterator is fully
+ * populated up-front; the shape matches Node for compatibility.
+ */
+export async function opendir(path: string): Promise<AsyncIterableIterator<Dirent>> {
+  const entries = await readdir(path, { withFileTypes: true });
+  let i = 0;
+  const iter: AsyncIterableIterator<Dirent> = {
+    [Symbol.asyncIterator](): AsyncIterableIterator<Dirent> {
+      return iter;
+    },
+    async next(): Promise<IteratorResult<Dirent>> {
+      if (i >= entries.length) {
+        return { value: undefined as unknown as Dirent, done: true };
+      }
+      return { value: entries[i++]!, done: false };
+    },
+    async return(): Promise<IteratorResult<Dirent>> {
+      i = entries.length;
+      return { value: undefined as unknown as Dirent, done: true };
+    },
+  };
+  return iter;
+}
+
+function datetimeToMs(dt: FileStat["modified"]): number | undefined {
+  if (dt === undefined) return undefined;
+  return Number(dt.seconds) * 1000 + dt.nanoseconds / 1_000_000;
+}
+
+function quote(s: string): string {
+  return `"${s.replace(/"/g, '\\"')}"`;
+}