npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@jnyross/code-factory

v1.3.2

Published

Bootstrap new repos from the Code Factory template.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

jnyrossjnyross

Keywords

code-factorytemplatebootstrapcliaidevops

Readme

Code Factory Template

Code Factory is a repo control-plane for autonomous coding + deterministic review.

This template implements the full pattern:

  • one machine-readable contract
  • risk-policy gate before expensive CI fanout
  • current-head SHA review discipline
  • current-head review score gate (5/5 policy)
  • canonical rerun comment dedupe
  • optional deterministic remediation agent loop
  • bot-only thread auto-resolve after clean rerun
  • browser evidence verification for UI/user-flow changes
  • safe auto-merge enablement for eligible PRs
  • incident -> harness-gap loop with weekly metrics

Contract (single source of truth)

All control-plane policy lives in ARCHITECTURE.yaml under control_plane:

  • riskTierRules
  • mergePolicy
  • docsDriftRules
  • reviewAgent
  • remediationAgent
  • browserEvidence
  • harnessGapLoop
  • branchProtection

Workflow Order

Control Plane workflow (.github/workflows/preflight.yml) runs jobs in this order:

  1. risk-policy-gate
  2. fanout: CI Pipeline, harness-smoke, and conditional Browser Evidence (only when UI-sensitive paths changed)
  3. risk-policy-finalize

For high tier changes, the gate auto-applies the PR label high-risk.

Greptile runs as the code review agent via GitHub App. Install the Greptile app and configure greptile.json in the repo root. The policy gate uses Greptile's check run directly (useCheckConclusionOnly: true).

greptile-event-handler workflow (.github/workflows/greptile-event-handler.yml) triggers on Greptile check completion: remediation (on failure) and auto-resolve of bot-only threads (on success).

Auto Merge workflow (.github/workflows/auto-merge-agent-prs.yml) enables GitHub auto-merge for same-repo, non-draft PRs unless the PR has label no-automerge.

SHA Discipline and Reruns

scripts/control-plane/risk-policy-gate.mjs enforces:

  • review check must be for current PR head SHA
  • stale review state is rejected
  • actionable findings in review summary comment fail the gate
  • review score policy can require machine-readable current-head score (for example 5/5) by tier
  • canonical rerun request comment is deduped by marker + sha:<head>
  • docs-drift checks are targeted to contract-interface paths (docsDriftRules.requireDocsForPaths), not all control-plane internals

control_plane.reviewAgent.scorePolicy enables deterministic review score gating:

  • set enabled: true
  • configure requiredScore / requiredScale (for example 5/5)
  • choose tiers with applyToTiers
  • enforce missing-score behavior with failIfScoreMissing
  • allow explicit audited bypass with overrideLabel (for example override-5of5)

Browser Evidence

For UI-sensitive paths, Browser Evidence requires a valid manifest:

  • path: harness/browser-evidence/manifest.json
  • freshness window and required flows defined in ARCHITECTURE.yaml

Capture uses Playwright to take real screenshots of required flows. If no BROWSER_EVIDENCE_BASE_URL is set, the capture script builds and serves the flowchart app locally.

Generate/update evidence manifest:

npm run harness:ui:capture-browser-evidence
npm run harness:ui:verify-browser-evidence

In CI, capture + verify are both run in Browser Evidence job.

Harness Gap Loop

harness-gap-loop workflow:

  • creates a harness-gap issue when a production-regression issue appears
  • runs weekly metrics (npm run harness:weekly-metrics)

Local Command Set

npm run typecheck
npm run lint
npm test
npm run build:ci --if-present
npm run harness:legal-chat:smoke
npm run harness:ui:pre-pr
npm run harness:ui:capture-browser-evidence
npm run harness:ui:verify-browser-evidence
npm run harness:risk-tier
npm run harness:weekly-metrics
npm run spec:normalize
npm run spec:validate
npm run spec:check
npm run control-plane:bootstrap-repo-settings -- owner/repo

In this template, typecheck, lint, and test delegate to the flowchart subproject.

Greptile Setup

code-factory now attempts to enable the new repository in the Greptile GitHub App installation immediately after repo creation.

  1. Install the Greptile GitHub App for your account/org.
  2. Create repos with code-factory (default behavior auto-enables Greptile access).
  3. Ensure greptile.json exists in the repo root (this template includes a default).
  4. Set statusCheck: true in greptile.json so the policy gate can enforce the Greptile check.
  5. The contract uses checkName: "Greptile Review" and useCheckConclusionOnly: true (check conclusion is authoritative).

Notes:

  • Auto-enable requires your gh auth user to have permission to add repos to the app installation.
  • To skip this step for one run, pass --no-greptile.
  • To target a non-default app slug, pass --greptile-app-slug <slug> (default: greptile).

Branch Protection

Merge blocking is enforced via GitHub branch protection requiring risk-policy-finalize.

  • code-factory applies this automatically when it creates the GitHub repo (default behavior).
  • For repos created from GitHub template UI, run:
node scripts/control-plane/apply-branch-protection.mjs owner/repo

Repository settings that make safe auto-merge practical are also bootstrapped:

  • enable auto-merge
  • enable squash merges
  • delete merged branches

For repos created from GitHub template UI, run:

node scripts/control-plane/bootstrap-repo-settings.mjs owner/repo

Note: GitHub may require a paid plan (or public repo) for private-repo branch protection.

Remediation Agent

Optional, disabled by default:

  • add a self-hosted runner for the repo
  • set repository variable ENABLE_REMEDIATION=true
  • optional variables: REMEDIATION_ENGINE, REMEDIATION_CODEX_MODEL, REMEDIATION_CODEX_PROFILE, REMEDIATION_CLAUDE_MODEL, REMEDIATION_OPENCODE_MODEL, REMEDIATION_VALIDATE_CMD, REMEDIATION_AGENT_CMD (required for custom engine)

When enabled, failed Greptile checks trigger deterministic in-branch remediation:

  1. verify current PR head matches event SHA (skip if stale)
  2. read review context (Greptile comments or summary)
  3. run local CLI agent (codex/claude/opencode/custom)
  4. run validation command
  5. commit + push fix to same PR branch

Agent Loop Files

  • ARCHITECTURE.yaml
  • AGENTS.md
  • prd.json
  • progress.txt (auto-created by ralph.sh on first run)

Tool Rule Files

  • .cursorrules
  • CLAUDE.md
  • .agent/rules/CodeFactory.md
  • prompt_template.txt
  • chatgpt_architecture_prd_prompt.txt
  • chatgpt_prd_format_prompt.txt

CLI Install

npm install -g @jnyross/code-factory

Or see npm package.

Create a New Project

Default (local scaffold + create/push GitHub repo):

code-factory my-next-app ~/Projects

Local only (opt out of GitHub creation):

code-factory my-next-app ~/Projects --no-github

Examples:

code-factory my-next-app --owner my-org --repo my-org/my-next-app --public

Compatibility alias:

  • new-project points to the same CLI command as code-factory.

Ralph Runner

ralph.sh supports engines:

  • codex (default)
  • claude
  • opencode (uses your OpenCode default unless OPENCODE_MODEL is set)
  • custom

And supports runner modes:

  • --mode pr (default): task execution is PR/control-plane driven.
  • --mode local: preserves the legacy local-only loop behavior.

Before task execution, ralph.sh runs a spec gate:

  1. normalize ARCHITECTURE.yaml + prd.json into canonical format
  2. validate both files strictly
  3. if still invalid, auto-repair with your selected local engine and retry (bounded)

PR mode loop (enforced order)

For each incomplete task in prd.json, PR mode runs:

  1. create/switch task/<id>-<slug>
  2. run coding agent
  3. run deterministic local checks with fixed env:
    • TZ=UTC
    • LC_ALL=C
    • CI=true
    • CODE_FACTORY_DETERMINISTIC_SEED=<fixed>
    • commands: npm run typecheck && npm run lint && npm test
  4. commit (only if changed), push branch
  5. create or reuse open PR for the branch
  6. capture + verify browser evidence (required for UI-sensitive changes)
  7. wait for required checks + review-agent state on current head SHA only
  8. if actionable findings exist: run remediation loop, push, rerun gates
  9. only then mark task complete in prd.json and append progress.txt

If any gate is missing, failing, stale, or inconclusive, completion is blocked.

Completion artifact

Each task produces a hard artifact:

artifacts/completion/<TASK_ID>.json

The artifact includes:

  • task metadata (task_id, branch, PR, head_sha)
  • UTC timestamps
  • command exit codes
  • acceptance-criteria evidence
  • final_status (complete or failed)
  • fail-closed failure reasons

Task completion is only allowed when artifact final_status is complete.

Defaults

  • RUN_MODE=pr
  • SPEC_REPAIR_ENABLED=true
  • SPEC_REPAIR_MAX_RETRIES=3

Deterministic completion contract:

  • checks run with fixed env: TZ=UTC, LC_ALL=C, CI=true
  • task completion artifact is written to artifacts/completion/<TASK_ID>.json
  • artifact includes task/head metadata, command results, acceptance evidence, and final status
  • tasks are marked complete only after all mode-specific gates pass

Examples:

./ralph.sh --once --mode pr
./ralph.sh --once --mode local
AGENT_ENGINE=claude ./ralph.sh --once --mode pr
AGENT_ENGINE=opencode ./ralph.sh --once --mode pr

Ralph PR Mode Runbook

Per open task, PR mode executes this deterministic sequence:

  1. create/switch to task branch
  2. run selected local agent
  3. run local preflight (typecheck, lint, test) under fixed env
  4. commit and push branch
  5. create/update PR
  6. run control-plane scripts against current PR head SHA:
    • risk-policy-gate.mjs --mode preflight
    • review-agent.mjs
    • risk-policy-gate.mjs --mode finalize (wait/retry for required checks)
  7. if review/actionable findings are detected, run remediation-loop.mjs, push, and re-check
  8. if control_plane.taskAdvancementPolicy.requireMergedPrBeforeNextTask=true, wait until PR is merged (or timeout/fail per policy)
  9. only mark task complete after finalize gate + score policy + merge requirement are all satisfied

Useful knobs:

  • BASE_BRANCH (default main)
  • TASK_BRANCH_PREFIX (default ralph/task)
  • PR_CHECK_TIMEOUT_SECONDS / PR_CHECK_POLL_SECONDS
  • PR_REMEDIATION_MAX_PASSES (default 10)
  • PR_DRY_RUN=true or --pr-dry-run for dry-ish local smoke runs