chore: import upstream snapshot with attribution

typescript/scripts/gen-presigned-url.ts

@@ -0,0 +1,112 @@
+/**
+ * Generate a presigned URL (GET + PUT) for the AWS S3 bucket configured in
+ * .env.development, and write them back to the same file under
+ * AWS_PRESIGNED_GET_URL / AWS_PRESIGNED_PUT_URL.
+ *
+ * Run:  pnpm tsx scripts/gen-presigned-url.ts
+ */
+import { readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { GetObjectCommand, PutObjectCommand, S3Client } from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+
+const ENV_FILE = resolve(process.cwd(), '../.env.development')
+// AWS SigV4 maximum for long-lived access keys is 7 days (604800s). For
+// role/STS creds, the cap is the session's remaining lifetime.
+const MAX_TTL_SEC = 604800
+const TTL_SEC = (() => {
+  const arg = process.argv[2]
+  const envVal = process.env.PRESIGNED_TTL_SEC
+  const raw = arg ?? envVal ?? String(MAX_TTL_SEC)
+  const parsed = Number.parseInt(raw, 10)
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid TTL: ${raw}`)
+  }
+  if (parsed > MAX_TTL_SEC) {
+    throw new Error(`TTL ${parsed}s exceeds AWS max ${MAX_TTL_SEC}s (7 days)`)
+  }
+  return parsed
+})()
+const TEST_KEY = `presigned-demo/${Date.now()}.txt`
+
+function parseEnv(raw: string): Map<string, string> {
+  const out = new Map<string, string>()
+  for (const line of raw.split('\n')) {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/)
+    if (m !== null) {
+      out.set(m[1] as string, m[2] as string)
+    }
+  }
+  return out
+}
+
+function writeEnvUpdates(raw: string, updates: Record<string, string>): string {
+  const keys = new Set(Object.keys(updates))
+  const lines = raw.split('\n')
+  const seen = new Set<string>()
+  const next = lines.map((line) => {
+    const m = line.match(/^([A-Z0-9_]+)=(.*)$/)
+    if (m === null) return line
+    const key = m[1] as string
+    if (!keys.has(key)) return line
+    seen.add(key)
+    return `${key}=${updates[key]}`
+  })
+  for (const key of keys) {
+    if (!seen.has(key)) next.push(`${key}=${updates[key]}`)
+  }
+  return next.join('\n')
+}
+
+async function main(): Promise<void> {
+  const raw = readFileSync(ENV_FILE, 'utf8')
+  const env = parseEnv(raw)
+  const bucket = env.get('AWS_S3_BUCKET') ?? ''
+  const region = env.get('AWS_DEFAULT_REGION') ?? 'us-east-1'
+  const accessKeyId = env.get('AWS_ACCESS_KEY_ID') ?? ''
+  const secretAccessKey = env.get('AWS_SECRET_ACCESS_KEY') ?? ''
+  if (bucket === '' || accessKeyId === '' || secretAccessKey === '') {
+    throw new Error(
+      'Missing AWS_S3_BUCKET / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY in .env.development',
+    )
+  }
+  const client = new S3Client({
+    region,
+    credentials: { accessKeyId, secretAccessKey },
+  })
+  const putUrl = await getSignedUrl(
+    client,
+    new PutObjectCommand({
+      Bucket: bucket,
+      Key: TEST_KEY,
+      ContentType: 'text/plain',
+    }),
+    { expiresIn: TTL_SEC },
+  )
+  const getUrl = await getSignedUrl(
+    client,
+    new GetObjectCommand({ Bucket: bucket, Key: TEST_KEY }),
+    { expiresIn: TTL_SEC },
+  )
+  const expiresAt = new Date(Date.now() + TTL_SEC * 1000).toISOString()
+  const updated = writeEnvUpdates(raw, {
+    AWS_PRESIGNED_KEY: TEST_KEY,
+    AWS_PRESIGNED_GET_URL: getUrl,
+    AWS_PRESIGNED_PUT_URL: putUrl,
+    AWS_PRESIGNED_EXPIRES_AT: expiresAt,
+  })
+  writeFileSync(ENV_FILE, updated, 'utf8')
+  client.destroy()
+  console.log(`bucket:   ${bucket}`)
+  console.log(`region:   ${region}`)
+  console.log(`key:      ${TEST_KEY}`)
+  console.log(`expires:  ${expiresAt}  (${TTL_SEC}s)`)
+  console.log(`put:      ${putUrl.slice(0, 80)}...`)
+  console.log(`get:      ${getUrl.slice(0, 80)}...`)
+  console.log(`wrote:    ${ENV_FILE}`)
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

typescript/scripts/gen-specs.ts

@@ -0,0 +1,121 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import * as Browser from '@struktoai/mirage-browser'
+import * as Core from '@struktoai/mirage-core'
+import * as Node from '@struktoai/mirage-node'
+
+import type { CommandSpec, Operand, Option, RegisteredCommand } from '@struktoai/mirage-core'
+
+const __dirname = resolve(fileURLToPath(import.meta.url), '..')
+const SPEC_ROOT = resolve(__dirname, '..', '..', 'spec', 'typescript')
+
+type ModuleBag = Record<string, unknown>
+
+function collectRegistrations(modules: ModuleBag[]): Record<string, RegisteredCommand[]> {
+  const out: Record<string, RegisteredCommand[]> = {}
+  for (const mod of modules) {
+    for (const [key, value] of Object.entries(mod)) {
+      if (!key.endsWith('_COMMANDS') || !Array.isArray(value)) continue
+      for (const rc of value as RegisteredCommand[]) {
+        if (!out[rc.name]) out[rc.name] = []
+        out[rc.name].push(rc)
+      }
+    }
+  }
+  return out
+}
+
+function metaFor(rcs: RegisteredCommand[]): Record<string, unknown> {
+  const resources = [
+    ...new Set(rcs.map((r) => r.resource).filter((r): r is string => r !== null)),
+  ].sort()
+  const filetypes = [
+    ...new Set(rcs.map((r) => r.filetype).filter((f): f is string => f !== null)),
+  ].sort()
+  return {
+    filetypes,
+    has_aggregate: rcs.some((r) => r.aggregate !== null),
+    has_provision: rcs.some((r) => r.provisionFn !== null),
+    has_write: rcs.some((r) => r.write),
+    resources,
+  }
+}
+
+function serializeOperand(op: Operand): Record<string, unknown> {
+  return { kind: op.kind, provided_by: [...op.providedBy] }
+}
+
+function serializeOption(o: Option): Record<string, unknown> {
+  return {
+    description: o.description,
+    long: o.long,
+    numeric_shorthand: o.numericShorthand,
+    repeatable: o.repeatable,
+    short: o.short,
+    value_kind: o.valueKind,
+    value_optional: o.valueOptional,
+  }
+}
+
+function serializeSpec(spec: CommandSpec, rcs: RegisteredCommand[]): Record<string, unknown> {
+  return {
+    _meta: metaFor(rcs),
+    description: spec.description,
+    ignore_tokens: [...spec.ignoreTokens].sort(),
+    options: spec.options.map(serializeOption),
+    positional: spec.positional.map(serializeOperand),
+    rest: spec.rest === null ? null : serializeOperand(spec.rest),
+  }
+}
+
+function sortedStringify(value: unknown): string {
+  return JSON.stringify(
+    value,
+    (_k, v) => {
+      if (v && typeof v === 'object' && !Array.isArray(v)) {
+        return Object.fromEntries(
+          Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)),
+        )
+      }
+      return v
+    },
+    2,
+  )
+}
+
+function emitVariant(name: string, modules: ModuleBag[]): void {
+  const registry = collectRegistrations(modules)
+  const outDir = resolve(SPEC_ROOT, name, 'general')
+  mkdirSync(outDir, { recursive: true })
+  const cmdNames = Object.keys(Core.SPECS).sort()
+  for (const cmd of cmdNames) {
+    const spec = Core.SPECS[cmd]
+    const rcs = registry[cmd] ?? []
+    const payload = serializeSpec(spec, rcs)
+    writeFileSync(resolve(outDir, `${cmd}.json`), sortedStringify(payload) + '\n')
+  }
+  console.log(`emitted ${cmdNames.length} specs to ${outDir}`)
+}
+
+function main(): void {
+  emitVariant('node', [Core as unknown as ModuleBag, Node as unknown as ModuleBag])
+  emitVariant('browser', [Core as unknown as ModuleBag, Browser as unknown as ModuleBag])
+}
+
+main()

typescript/scripts/load-env.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Source this file to export every key from .env.development as a shell env var.
+# Works from any cwd. Resolves .env.development relative to this script's location.
+# Parses dotenv format directly (no shell evaluation), so values containing
+# `&`, `$`, `(`, etc. don't trip the shell parser.
+#
+# Usage:
+#   source typescript/scripts/load-env.sh    # zsh / bash, from repo root
+#   . typescript/scripts/load-env.sh         # POSIX-compatible
+#
+# After sourcing, run any example from any directory:
+#   pnpm tsx ../examples/typescript/trello/trello_fuse.ts
+
+# Resolve script-relative path (zsh + bash compatible).
+if [ -n "${BASH_SOURCE[0]:-}" ]; then
+  __HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+elif [ -n "${(%):-%x}" ]; then
+  __HERE="$(cd "$(dirname "${(%):-%x}")" && pwd)"
+else
+  echo "load-env: cannot determine script location (must be sourced)" >&2
+  return 1 2>/dev/null || exit 1
+fi
+__ENV="$(cd "$__HERE/../.." && pwd)/.env.development"
+unset __HERE
+if [ ! -f "$__ENV" ]; then
+  echo "load-env: $__ENV not found" >&2
+  unset __ENV
+  return 1 2>/dev/null || exit 1
+fi
+
+# Parse dotenv lines: KEY=VALUE, skip comments / blanks. Strip optional
+# matching surrounding quotes. No shell evaluation, so values containing
+# `&`, `$`, `(`, etc. are safe.
+__count=0
+while IFS= read -r __line || [ -n "$__line" ]; do
+  case "$__line" in
+    ''|'#'*) continue ;;
+  esac
+  __key="${__line%%=*}"
+  __val="${__line#*=}"
+  case "$__key" in
+    *[!A-Za-z0-9_]*|'') continue ;;
+  esac
+  # Strip matching wrapping quotes.
+  case "$__val" in
+    \"*\") __val="${__val#\"}"; __val="${__val%\"}" ;;
+    \'*\') __val="${__val#\'}"; __val="${__val%\'}" ;;
+  esac
+  export "$__key=$__val"
+  __count=$((__count + 1))
+done < "$__ENV"
+
+echo "loaded $__count vars from $__ENV"
+unset __ENV __line __key __val __count

typescript/scripts/precommit-run.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+tool="$1"
+flag="$2"
+shift 2
+
+files=()
+for f in "$@"; do
+  files+=("${f#typescript/}")
+done
+
+cd "$(dirname "$0")/.."
+exec pnpm exec "$tool" "$flag" "${files[@]}"