garrytan/gstack · error · Error

--out-dir requires a directory path

Error message

--out-dir requires a directory path

What it means

Thrown by the OUT_DIR IIFE in scripts/gen-skill-docs.ts:162 when --out-dir is present but no value follows (it is the last token, or the = form yields empty). --out-dir redirects Claude SKILL.md + section output to a separate untracked directory and rewrites the section-base path so section Reads resolve to the rendered copy.

Source

Thrown at scripts/gen-skill-docs.ts:162

  }
  return val;
})();

// ─── Out-dir (dev workspace render isolation) ───────────────
// --out-dir <abs-dir> redirects Claude SKILL.md + section output to a separate
// (untracked) directory instead of writing in place, AND rewrites the literal
// section-base path (`~/.claude/skills/gstack/<skill>/sections/`) inside the
// generated content to point at the out-dir, so section Reads resolve to the
// rendered copy rather than the global install. Used by bin/dev-setup to render
// the gbrain `:user` variant for a Conductor workspace without dirtying tracked
// source. Default (unset) = in-place, behavior unchanged. Claude host only.
const OUT_DIR_ARG = process.argv.find(a => a.startsWith('--out-dir'));
const OUT_DIR: string | null = (() => {
  if (!OUT_DIR_ARG) return null;
  const val = OUT_DIR_ARG.includes('=')
    ? OUT_DIR_ARG.split('=')[1]
    : process.argv[process.argv.indexOf(OUT_DIR_ARG) + 1];
  if (!val) throw new Error('--out-dir requires a directory path');
  return path.resolve(val);
})();

/**
 * When rendering to an out-dir, repoint the literal section-base path at the
 * out-dir so section Reads resolve to the rendered copy, not the global install.
 * Surgical: ONLY paths containing `/sections/` are rewritten — bin/, browse/,
 * docs/ references keep pointing at `~/.claude/skills/gstack` (the global
 * install, which still works). No-op when --out-dir is unset.
 */
function rewriteSectionBase(content: string): string {
  if (!OUT_DIR) return content;
  return content.replace(
    /~\/\.claude\/skills\/gstack\/([^\s)`"'*]+\/sections\/)/g,
    `${OUT_DIR}/$1`,
  );
}

View on GitHub (pinned to 94993f7401)

Solutions

1. Append a path: `--out-dir /tmp/render`
2. Use the equals form: `--out-dir=/tmp/render`
3. Ensure the env var feeding the path is set and non-empty before invoking

Example fix

// before
bun run gen:skill-docs -- --host claude --out-dir
// after
bun run gen:skill-docs -- --host claude --out-dir /tmp/gbrain-render

const i = process.argv.indexOf('--out-dir');
if (i !== -1) {
  const eq = process.argv[i].includes('=');
  const next = eq ? process.argv[i].split('=')[1] : process.argv[i + 1];
  if (!next) {
    console.error('--out-dir requires a directory path');
    process.exit(2);
  }
}

When it happens

Trigger: `bun run gen:skill-docs -- --host claude --out-dir` with nothing after. `--out-dir=` with empty value. Shell variable expansion producing an empty path.

Common situations: Conditionally appending --out-dir $DIR in a script where DIR is unset. Trailing flag at end of an argv array. Quoting bug dropping the path.

Related errors

• Unknown host: ${val}. Use ${ALL_HOST_NAMES.join(', ')}, or a
• Unknown model: ${val}. Use ${ALL_MODEL_NAMES.join(', ')}, or
• Unknown catalog mode: ${val}. Use 'trim' (default) or 'full'
• Unknown explain level: ${val}. Use 'default' or 'terse'.
• Missing value for --shards

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/fe73f06f5e53260b. Report an issue: GitHub.