@1aboveio/skills 0.10.0

package/runtime/skills/distribution/scripts/bundles.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { emitKeypressEvents } from 'node:readline';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { isMainModule } from '../../engineering/engineering-runtime/scripts/main-module.mjs';
+
+// The coordinator is one command rendered into two transports: the private checkout and the
+// unpacked @1aboveio/skills package. Both defaults below are anchored on this file's own location,
+// so neither the private repository root nor the process working directory is ever assumed. A
+// caller that lays the payload out differently injects both paths instead (see runCli's flags).
+const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
+const DISTRIBUTION_DIR = resolve(SCRIPT_DIR, '..');
+const DEFAULT_RECIPES_PATH = join(DISTRIBUTION_DIR, 'generated', 'recipes.json');
+const DEFAULT_LOCAL_ROOT = resolve(DISTRIBUTION_DIR, '../..');
+const NATIVE_ADD_SOURCE = /^(npx skills@\S+ add )(\S+)(?= )/;
+// Which generated command form to execute, most specific first. The private-checkout render emits the
+// Git transports (`https`/`ssh`); the public-npm render emits a single `local` command because the
+// first-party payload ships inside the package and is never fetched. The enum is not overloaded to
+// carry the channel — a `local` command means a local path source, which is what it is.
+const COMMAND_TRANSPORTS = ['local', 'https'];
+// Groups that exist only as an implementation dependency of the selectable ones. Exported because it
+// is the single source of truth for the rule that spans every public-facing surface: a support group
+// is never presented as something a user picks. The picker, `list`, the plan and the generated
+// package README all derive their answer from here rather than each re-listing the ids.
+export const SUPPORT_GROUPS = new Set(['harness-runtime']);
+const ACTIONS = new Set(['install', 'update']);
+
+export const selectorTerminalControl = Object.freeze({
+  enter: '\x1b[?1049h\x1b[?25l',
+  redraw: '\x1b[2J\x1b[H',
+  exit: '\x1b[?25h\x1b[?1049l',
+});
+
+export function resolveBundleTransport({ recipesPath, localRoot } = {}) {
+  return {
+    recipesPath: recipesPath ? resolve(recipesPath) : DEFAULT_RECIPES_PATH,
+    localRoot: localRoot ? resolve(localRoot) : DEFAULT_LOCAL_ROOT,
+  };
+}
+
+function readRecipes(recipesPath) {
+  let contents;
+  try {
+    contents = readFileSync(recipesPath, 'utf8');
+  } catch {
+    throw new Error(`Bundle recipes not found: ${recipesPath}`);
+  }
+  return JSON.parse(contents);
+}
+
+function assertLocalRoot(localRoot) {
+  if (!statSync(localRoot, { throwIfNoEntry: false })?.isDirectory()) {
+    throw new Error(`Bundle local source root is not a directory: ${localRoot}`);
+  }
+  return localRoot;
+}
+
+export function bundleCatalog(transport = {}) {
+  return readRecipes(resolveBundleTransport(transport).recipesPath).groups
+    .filter((group) => !SUPPORT_GROUPS.has(group.id))
+    .map((group) => ({
+      id: group.id,
+      displayName: group.displayName,
+      members: group.install.steps.flatMap((step) => step.members),
+    }));
+}
+
+function shellArgument(value) {
+  return `'${value.replaceAll("'", String.raw`'\''`)}'`;
+}
+
+// Point the recipe's native `add` step at the local first-party payload, whatever source the
+// generated recipe declares. Matching the native step rather than the private repository name is
+// what makes one planning implementation serve both transports: a public recipe that never mentions
+// the private repository relocates the same way, and no reachable path can leave a private fetch in
+// the plan. (This file ships inside the public package, so it must not name that repository either.)
+function localFirstPartyCommand(command, localRoot, groupId) {
+  if (!NATIVE_ADD_SOURCE.test(command)) {
+    throw new Error(`Bundle ${groupId} source first-party has no native add step to relocate: ${command}`);
+  }
+  return command.replace(NATIVE_ADD_SOURCE, (_match, prefix) => `${prefix}${shellArgument(localRoot)}`);
+}
+
+export function planBundleCommands(action, groupIds, { yes = false, ...transport } = {}) {
+  if (!ACTIONS.has(action)) throw new Error(`Unsupported bundle action: ${action}`);
+  const { recipesPath, localRoot } = resolveBundleTransport(transport);
+  const recipes = readRecipes(recipesPath);
+  assertLocalRoot(localRoot);
+  const groups = new Map(recipes.groups.map((group) => [group.id, group]));
+  const commands = [];
+  const seen = new Set();
+
+  for (const groupId of groupIds) {
+    const group = groups.get(groupId);
+    if (!group || SUPPORT_GROUPS.has(groupId)) throw new Error(`Unknown bundle: ${groupId}`);
+    for (const step of group[action].steps) {
+      const generated = COMMAND_TRANSPORTS
+        .map((transport) => step.commands.find((candidate) => candidate.transport === transport))
+        .find(Boolean);
+      if (!generated) throw new Error(`Bundle ${groupId} has no supported command for source ${step.sourceId}`);
+      let command = step.sourceId === 'first-party'
+        ? localFirstPartyCommand(generated.command, localRoot, groupId)
+        : generated.command;
+      if (yes) command += ' --yes';
+      if (seen.has(command)) continue;
+      seen.add(command);
+      commands.push({
+        groupId,
+        groupName: group.displayName,
+        sourceId: step.sourceId,
+        command,
+        cwd: localRoot,
+        failureMessage: step.onFailure.message,
+      });
+    }
+  }
+  return commands;
+}
+
+export function runBundleCommands(commands, {
+  execute = (command, cwd) => spawnSync('/bin/bash', ['-lc', command], { cwd, stdio: 'inherit' }),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  for (const planned of commands) {
+    stdout.write(`\nInstalling ${planned.groupName} (${planned.sourceId})...\n`);
+    const result = execute(planned.command, planned.cwd);
+    if (result.status !== 0) {
+      stderr.write(`${planned.failureMessage}\n`);
+      return Number.isInteger(result.status) ? result.status : 1;
+    }
+  }
+  return 0;
+}
+
+function usage() {
+  return `Usage:
+  node skills/distribution/scripts/bundles.mjs list [--recipes <path>]
+  node skills/distribution/scripts/bundles.mjs <install|update> [--group <id> ... | --all] [--dry-run] [--yes] [--recipes <path>] [--local-root <path>]
+`;
+}
+
+function parseArgs(args) {
+  const [action = 'install', ...options] = args;
+  const parsed = { action, groupIds: [], all: false, dryRun: false, yes: false };
+  for (let index = 0; index < options.length; index += 1) {
+    const option = options[index];
+    if (option === '--group') {
+      const value = options[index + 1];
+      if (!value) throw new Error('--group requires a bundle id');
+      parsed.groupIds.push(...value.split(',').map((id) => id.trim()).filter(Boolean));
+      index += 1;
+    } else if (option === '--recipes' || option === '--local-root') {
+      const value = options[index + 1];
+      if (!value) throw new Error(`${option} requires a path`);
+      parsed[option === '--recipes' ? 'recipesPath' : 'localRoot'] = value;
+      index += 1;
+    } else if (option === '--all') parsed.all = true;
+    else if (option === '--dry-run') parsed.dryRun = true;
+    else if (option === '--yes') parsed.yes = true;
+    else throw new Error(`Unknown option: ${option}`);
+  }
+  if (parsed.all && parsed.groupIds.length > 0) throw new Error('Use either --all or --group, not both');
+  return parsed;
+}
+
+function printCatalog(stdout = process.stdout, catalog = bundleCatalog()) {
+  for (const bundle of catalog) {
+    stdout.write(`${bundle.displayName} (${bundle.id})\n`);
+  }
+}
+
+export function updateSelection(state, key, itemCount) {
+  const selected = new Set(state.selected);
+  if (key === 'up') return { cursor: (state.cursor - 1 + itemCount) % itemCount, selected };
+  if (key === 'down') return { cursor: (state.cursor + 1) % itemCount, selected };
+  if (key === 'space') {
+    if (selected.has(state.cursor)) selected.delete(state.cursor);
+    else selected.add(state.cursor);
+  }
+  return { cursor: state.cursor, selected };
+}
+
+export function renderSelector(catalog, state) {
+  const rows = catalog.map((bundle, index) => {
+    const pointer = index === state.cursor ? '>' : ' ';
+    const mark = state.selected.has(index) ? '[x]' : '[ ]';
+    const count = bundle.members.length;
+    return `${pointer} ${mark} ${bundle.displayName}  ${count} skill${count === 1 ? '' : 's'}`;
+  });
+  const focused = catalog[state.cursor];
+  return [
+    'Select skill bundles',
+    ...rows,
+    '',
+    `Includes: ${focused.members.join(', ')}`,
+    '',
+    'up/down move   space select   enter confirm',
+  ].join('\n');
+}
+
+async function promptForGroups(catalog, { stdin = process.stdin, stdout = process.stdout } = {}) {
+  if (!stdin.isTTY || !stdout.isTTY) {
+    throw new Error('Choose bundles with --group <id> or --all when no interactive terminal is available');
+  }
+  emitKeypressEvents(stdin);
+  stdin.setRawMode(true);
+  stdin.resume();
+  let state = { cursor: 0, selected: new Set() };
+
+  const draw = () => {
+    stdout.write(`${selectorTerminalControl.redraw}${renderSelector(catalog, state)}\n`);
+  };
+  stdout.write(selectorTerminalControl.enter);
+  draw();
+
+  return new Promise((resolveSelection, rejectSelection) => {
+    const finish = (error) => {
+      stdin.off('keypress', onKeypress);
+      stdin.setRawMode(false);
+      stdin.pause();
+      stdout.write(selectorTerminalControl.exit);
+      if (error) rejectSelection(error);
+      else resolveSelection([...state.selected]
+        .sort((left, right) => left - right)
+        .map((index) => catalog[index].id));
+    };
+    const onKeypress = (_input, key = {}) => {
+      if (key.ctrl && key.name === 'c') return finish(new Error('Bundle selection cancelled'));
+      if (key.name === 'return' || key.name === 'enter') return finish();
+      const name = key.name === 'space' ? 'space' : key.name;
+      if (!['up', 'down', 'space'].includes(name)) return undefined;
+      state = updateSelection(state, name, catalog.length);
+      draw();
+      return undefined;
+    };
+    stdin.on('keypress', onKeypress);
+  });
+}
+
+export async function runCli(args) {
+  try {
+    const parsed = parseArgs(args);
+    const transport = { recipesPath: parsed.recipesPath, localRoot: parsed.localRoot };
+    if (parsed.action === 'list') {
+      printCatalog(process.stdout, bundleCatalog(transport));
+      return 0;
+    }
+    if (!ACTIONS.has(parsed.action)) {
+      process.stderr.write(usage());
+      return 2;
+    }
+    const catalog = bundleCatalog(transport);
+    const groupIds = parsed.all
+      ? catalog.map((bundle) => bundle.id)
+      : parsed.groupIds.length > 0
+        ? parsed.groupIds
+        : await promptForGroups(catalog);
+    if (groupIds.length === 0) throw new Error('Select at least one bundle');
+    const commands = planBundleCommands(parsed.action, groupIds, { ...transport, yes: parsed.yes });
+    if (parsed.dryRun) {
+      for (const planned of commands) {
+        process.stdout.write(`\n${planned.groupName} / ${planned.sourceId}\n${planned.command}\n`);
+      }
+      return 0;
+    }
+    return runBundleCommands(commands);
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
+  process.exitCode = await runCli(process.argv.slice(2));
+}

package/runtime/skills/engineering/engineering-runtime/scripts/main-module.mjs

@@ -0,0 +1,80 @@
+// The one ESM main-module guard every skill script in this repo uses.
+//
+// Not a style preference — the hand-written versions of this three-line check had two opposite
+// silent failure modes in production, and both shipped:
+//
+//   #718  `import.meta.url === pathToFileURL(process.argv[1]).href`
+//         Node resolves `import.meta.url` to the REAL path; `argv[1]` keeps whatever the caller
+//         typed. A skills install is a symlink farm (`~/.claude/skills/<skill>` → the checkout),
+//         so through the install path the two never match: the CLI does not run and node exits 0.
+//         `coverage-ledger.mjs` shipped this and recorded a false pass in the wild
+//         (a consumer product repo: epic #352, unit #379, PR #384) on a gate whose only job is to
+//         say no. Fails OPEN, invisibly — "passed" and "never ran" are byte-identical evidence.
+//
+//   #446  `fs.realpathSync(process.argv[1]) === …`, unguarded.
+//         `node -` sets `argv[1]` to the literal string `"-"` — truthy, so the usual
+//         `process.argv[1] &&` prefix does not save it — and realpath throws ENOENT at MODULE
+//         LOAD, before a line of the module's own code runs. The module cannot be imported by
+//         anything that does not launch it as a file. Fails CLOSED, at load.
+//
+// So the contract has exactly two obligations, one per failure mode:
+//   1. realpath BOTH sides before comparing, so a symlinked invocation is still the main module;
+//   2. degrade to `false` — "not the main module" — for anything that does not resolve, never throw.
+//
+// WHY IT IS SHARED RATHER THAN COPIED. PR #278 fixed twelve copies of failure mode #718 by hand and
+// mechanized nothing. Five weeks later `mergify/scripts/audit.mjs` was written with the pre-#278
+// form, and `coverage-ledger.mjs` survived the whole pass because it spelled the same bug a third
+// way that #278's grep did not match. One module plus `main-guard-hygiene.test.mjs` is what stops
+// the next copy: there is now no second place for this logic to drift to, and adding one fails CI.
+//
+// WHERE IT LIVES, AND WHY HERE. Native Skills CLI installation flattens selected packages into
+// sibling directories under `~/.agents/skills`, while this repository nests them under
+// `skills/engineering`. A Workflow consumer at `<skill>/scripts` therefore imports
+// `../../engineering-runtime/scripts/main-module.mjs`: the same specifier reaches this package in
+// both layouts. Claude Code launches through a per-skill symlink into the canonical store; node's
+// realpath-aware module resolution and this predicate preserve that path as well.
+//
+// `engineering-runtime` owns the helper as an installable support package rather than a user
+// capability. `resolve-issues/scripts/sandbox-selftest.mjs` reconstructs the same sibling layout and
+// links this package beside the skill under test. Every consumer imports this package directly.
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Is the module identified by `importMetaUrl` the script node was launched with?
+ *
+ * Symlink-transparent, and total: any input that does not resolve to a real file answers `false`
+ * instead of throwing, so importing a CLI module is always safe.
+ *
+ * @param {string} importMetaUrl the caller's own `import.meta.url`
+ * @returns {boolean}
+ */
+export function isMainModule(importMetaUrl) {
+  const entry = process.argv[1];
+  if (typeof entry !== 'string' || entry === '') return false; // imported, or an embedding harness
+
+  let entryPath;
+  try {
+    entryPath = fs.realpathSync(entry);
+  } catch {
+    return false; // #446: `node -` gives "-"; some harnesses give a path that is not on disk
+  }
+
+  let selfPath;
+  try {
+    selfPath = fileURLToPath(importMetaUrl);
+  } catch {
+    return false; // a data:/http: module has no path to compare, so it is never the launched script
+  }
+  try {
+    // #718: the launched side is resolved above, so this side must be too. Under Node's default
+    // resolution `import.meta.url` is already real and this is a no-op; under `--preserve-symlinks`
+    // it is the half that makes the comparison hold.
+    selfPath = fs.realpathSync(selfPath);
+  } catch {
+    // The module is executing, so it existed a moment ago. Compare what we have rather than
+    // claiming "not main" — a vanished file should not silently disable a running CLI.
+  }
+
+  return entryPath === selfPath;
+}

package/skills/backend/airflow-dag-develop/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/backend/airflow-dag-develop/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: airflow-dag-develop
+description: Airflow DAG architecture and conventions. Read when designing, creating, or debugging DAGs — covers CLI validation, environment-based scheduling, and pytest integrity tests.
+user-invocable: true
+---
+
+# Airflow DAG Development Patterns
+
+## 1. Quick DAG Validation with Airflow CLI
+
+Use these commands for fast feedback during development:
+
+```bash
+# List import errors (fastest check - catches syntax and import issues)
+airflow dags list-import-errors
+
+# Full lint check (comprehensive - catches best practice violations)
+airflow dags lint
+```
+
+**When to use:**
+- `list-import-errors`: During active development for quick syntax/import validation
+- `lint`: Before commits to catch style and best practice issues
+
+## 2. Environment-Based Schedule Override
+
+Disable schedules in local development to prevent accidental runs:
+
+```python
+import os
+from datetime import datetime
+from airflow import DAG
+
+def get_schedule(production_schedule: str) -> str | None:
+    """Return None for local dev, actual schedule for deployed environments.
+
+    Set AIRFLOW_ENV=local in .env for local development.
+    Cloud Run deployments set AIRFLOW_ENV=dev|staging|prod.
+    """
+    env = os.getenv("AIRFLOW_ENV", "local")
+    if env == "local":
+        return None
+    return production_schedule
+```
+
+**Usage in DAG:**
+```python
+with DAG(
+    dag_id="my_dag",
+    schedule=get_schedule("0 4 * * *"),  # Daily 4 AM in prod, None locally
+    start_date=datetime(2024, 1, 1),
+    catchup=False,
+) as dag:
+    ...
+```
+
+**Environment setup:**
+- **Local:** Add `AIRFLOW_ENV=local` to `.env`
+- **Cloud Run:** Set via cloudbuild.yaml substitutions (`_AIRFLOW_ENV: dev|staging|prod`)
+
+## 3. Pytest DAG Integrity Tests
+
+Standard pytest patterns for validating DAG quality:
+
+```python
+# tests/test_dag_integrity.py
+import pytest
+from airflow.models import DagBag
+
+@pytest.fixture(scope="session")
+def dagbag():
+    return DagBag(dag_folder="dags/", include_examples=False)
+
+def test_no_import_errors(dagbag):
+    """Verify all DAGs load without import errors."""
+    assert not dagbag.import_errors, f"DAG import errors: {dagbag.import_errors}"
+
+def test_dags_have_tags(dagbag):
+    """Verify all DAGs have at least one tag for organization."""
+    for dag_id, dag in dagbag.dags.items():
+        assert dag.tags, f"DAG {dag_id} has no tags"
+
+def test_dags_have_owner(dagbag):
+    """Verify all DAGs have an owner in default_args."""
+    for dag_id, dag in dagbag.dags.items():
+        assert dag.default_args.get("owner"), f"DAG {dag_id} missing owner"
+
+def test_no_cycles(dagbag):
+    """Verify DAGs don't have circular dependencies."""
+    for dag_id, dag in dagbag.dags.items():
+        # DagBag already validates this, but explicit test for clarity
+        assert dag.topo_sort(), f"DAG {dag_id} has cycles"
+```
+
+**Run tests:**
+```bash
+# Run all DAG tests
+pytest tests/test_dag_integrity.py -v
+
+# Run specific test
+pytest tests/test_dag_integrity.py::test_no_import_errors -v
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Check import errors | `airflow dags list-import-errors` |
+| Lint DAGs | `airflow dags lint` |
+| Run integrity tests | `pytest tests/test_dag_integrity.py -v` |
+| Trigger manual run | `airflow dags trigger <dag_id>` |

package/skills/backend/app-debug/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/backend/app-debug/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: app-debug
+description: "Diagnose runtime failures in deployed Cloud Run services — 5xx/422 errors, tracebacks, Next.js SSR/hydration or Server Action failures, DB/Secret Manager connection errors, cold-start timeouts, container OOM. NOT for build or deploy failures (cloud-debug)."
+---
+
+# App Debug
+
+---
+
+## Step 1: Gather Context
+
+Collect before touching logs:
+
+- **Service name** — which service? (`a1-engine`, `a1-portal`, `a1-admin`, `a1-engine-query`, `a1-forex`)
+- **Environment** — `dev` or `prod`
+- **Error description** — what is the symptom? (HTTP status, error message, UI behavior)
+- **Timestamp** — when did it start? (approximate is fine)
+- **Recent deploy?** — did a new revision go out recently?
+
+Full service names follow the pattern: `{service}-{env}` (e.g. `a1-engine-dev`, `a1-portal-prod`).
+
+---
+
+## Step 2: Fetch Log Tail
+
+**Always start with errors only.** Broaden only if errors return nothing useful.
+
+### Errors-only (start here)
+
+```bash
+gcloud logging read \
+  'resource.type="cloud_run_revision" AND resource.labels.service_name="a1-engine-dev" AND severity>=ERROR' \
+  --project cosmic-heaven-479306-v5 \
+  --limit 20 \
+  --format="value(timestamp,textPayload)"
+```
+
+Replace `a1-engine-dev` with the target service name.
+
+### Broader log tail (if errors-only is empty)
+
+```bash
+gcloud run services logs read a1-engine-dev \
+  --region us-central1 \
+  --project cosmic-heaven-479306-v5 \
+  --limit 50
+```
+
+### Check current revision and env vars
+
+```bash
+gcloud run services describe a1-engine-dev \
+  --region us-central1 \
+  --project cosmic-heaven-479306-v5 \
+  --format="yaml(spec.template.spec.containers[0].env, spec.template.spec.containers[0].resources, status.latestReadyRevisionName)"
+```
+
+### Check secret versions (if secret errors suspected)
+
+```bash
+gcloud secrets versions list database-url-a1-dev \
+  --project cosmic-heaven-479306-v5
+```
+
+---
+
+## Step 3: Classify the Error
+
+Map what you found in logs to one error class:
+
+- **App Error** — Python traceback, unhandled exception, 500 from FastAPI, Next.js render crash
+- **DB Error** — connection refused, auth failure, Tortoise config error, Cloud SQL proxy issue
+- **Secret Error** — permission denied on Secret Manager, secret not found, wrong version
+- **Config Error** — missing env var, wrong PORT, wrong Cloud SQL instance name, bad DB URL format
+- **Resource Error** — OOM kill, DEADLINE_EXCEEDED, cold start timeout, container exit code 137
+
+---
+
+## Step 4: Form Hypotheses
+
+Read `references/common-errors.md` now. Match the log output against the known patterns to confirm your hypothesis before proceeding.
+
+Then pick the top 3 causes ranked by probability based on what the logs actually show. Example:
+
+1. **(Most likely)** Wrong secret version for `database-url-a1-dev` — password mismatch after DB rotation
+2. Cloud SQL proxy not receiving connections — `CLOUD_SQL_INSTANCE` env var missing or wrong format
+3. Cold start OOM — memory limit too low, service hitting 256Mi default under load
+
+Do not list more than 3.
+
+---
+
+## Step 5: Targeted Fix
+
+For each hypothesis, apply the verify + resolve steps from `references/common-errors.md`.
+
+If the error class is **App Error** (Python traceback, Next.js render crash, unhandled exception):
+- Check the first line of the traceback — unhandled import errors appear here at startup
+- Look for `ConfigurationError` or `OperationalError` near the top — indicates Tortoise/DB init failure during lifespan startup
+- If traceback points to a specific route handler file — it's a runtime exception, not a startup issue
+- Route to Cory (backend tracebacks) or Suzzy (Next.js/frontend) with the exact traceback and file location
+
+For all other error classes (DB, Secret, Config, Resource): follow the matching pattern in `references/common-errors.md` for the exact `gcloud` commands to verify and resolve.
+
+---
+
+## Reference
+
+`references/common-errors.md` — full catalogue of known error patterns, symptoms, causes, and fix commands for this stack. Read it in Step 4; refer back in Step 5.