Interview Planner

A comprehensive interview management platform for streamlining the hiring process.

CI/CD Status

Features

• Interview scheduling and management
• Candidate evaluation and scoring
• Multi-tenant organization support
• Real-time collaboration features
• Comprehensive reporting and analytics

Technology Stack

• Frontend: React, TypeScript, Vite
• Backend: Supabase (PostgreSQL, Edge Functions)
• Testing: Vitest, Playwright
• CI/CD: GitHub Actions
• Deployment: Automated via GitHub Actions

Getting Started

Prerequisites

• Node 22 — this is the development and CI line pinned by .nvmrc. The machine-readable package.json engine also supports compatible releases on Node 20, 22, and 24, and intentionally rejects Node 26 and odd-numbered lines.
• npm 11, pinned by packageManager in package.json.
• Supabase CLI
• Docker, for the local Supabase stack

Installation

1. Clone the repository:

git clone https://github.com/yardsticklucas/interview-planner.git
cd interview-planner

2. Prepare the workspace:

bash scripts/bootstrap-workspace.sh --target dev --force

One command replaces the old install-then-configure pair. It checks your toolchain, runs npm ci when dependencies are missing, verifies the pinned Supabase CLI, reserves a dev-server port no other checkout of this repo is holding, and writes .env.local. It prepares the workspace and never starts a server, so it is safe to re-run and safe to use as a Codespaces postCreateCommand.

Dependency install scripts are deny-by-default under npm 11. The root package.json allowScripts map records every dependency with an install-time script: true means the script is required and reviewed; false means it is intentionally blocked. When a dependency change adds a pending script, inspect it before changing the map, then run npm run check:install-scripts and confirm it reports that every script is classified. Do not approve scripts interactively without committing the reviewed classification.

The default target is the hosted remote dev project. Every worktree can run its own local web server while sharing that hosted dev database. --force refreshes the Supabase target settings but preserves existing local tool settings such as OAuth proof, Slack, and TheirStack variables. Put new operator-only settings in the ignored .env.local.user file; they are kept local and are not uploaded to Supabase. The browser-safe dev key can be supplied through the environment, the worktree's ignored key file, or the primary main checkout's ignored key file. See the remote dev environment runbook.

For hosted dev, .env.local contains the browser connection only: the hosted Supabase URL, its publishable key, and this worktree's port. It must not contain the local database URL or a service-role/server key. The real hosted-dev database password and server key are kept in the ignored supabase/dev-env/credentials.local.env; scripts/dev-env.sh reads them only for commands that need direct database or server access, and does not upload them to the browser or commit them.

3. Start the dev server:

npm run dev

Use bash scripts/bootstrap-workspace.sh --target local --force and npm run supabase:start only when a task explicitly needs the disposable local Supabase stack, such as a local SQL contract or destructive reset.

Open the app at http://127.0.0.1:<your port>. On localhost every route currently shows the "Page not found" screen: the bootstrap points VITE_PUBLIC_JOB_BOARD_BASE_URL at the same origin the dev server runs on, so the app treats localhost as the public job board host. Changing that variable to http://jobs.localhost:<your port> in .env.local frees up localhost too.

One dev-server port per checkout

Each checkout gets its own port from the 5173-5192 range, written to .env.local as VITE_DEV_PORT. Two worktrees can run dev servers at the same time without either one taking the other's port. The bootstrap picks a free port and records it; to see the one this checkout holds:

bash scripts/bootstrap-workspace.sh --print-port

Writing .env.local yourself

If you would rather not run the bootstrap:

cp .env.example .env.local

.env.example carries a working local-stack Supabase URL and publishable key, so the copy gives you a workspace that runs rather than one that returns 401 on every request. That manual path is for an explicitly local workspace; the normal hosted-dev path is the bootstrap command above. The bootstrap picks the next reserved port if another checkout already holds the lower ports.

Running Tests

# Run the supported local main suite
npm test

# Run the wrapped main suite directly
npm run test:all

# Run explicitly quarantined tests
npm run test:quarantine

# Run tests with coverage
npm run test:coverage

# Clean up stale local Vitest processes and gate locks
npm run test:cleanup

# Run the single-fork diagnostic flow for known offenders
npm run test:doctor

# Update test baseline
npm run test:update-baseline

The main suite auto-discovers new *.test.* and *.spec.* files under src/ and supabase/. To keep a known-bad file out of the blocking suite, rename it with a quarantine suffix such as .quarantined.test.ts or .quarantined.spec.tsx, then run it with npm run test:quarantine. Use npm run test:raw only for low-level Vitest debugging. The supported local test runtime is Node 22, matching .nvmrc and the test workflows.

Database Migrations

# Apply migrations locally
npx supabase db reset --local

# Create a new migration
npx supabase migration new <migration_name>

# Check migration sync status
./scripts/monitor-migration-sync.sh dev

Local resets also load supabase/seed.sql, which creates deterministic local-only test logins. Use password localdev123! with [email protected], [email protected], or [email protected]; see AGENTS.md for the intended plan/feature coverage of each account.

These accounts exist only in the loopback stack. Shared browser QA runs against hosted dev, whose logins come from ./scripts/dev-env.sh seed (owner-<suffix>@yardstick-dev.invalid, admin2-…, member-…, all with password devqa123!, in org dev-qa-<suffix>). See docs/development/remote-dev-environment-runbook.md. Reach for the local accounts only for migration authoring, fresh-database checks, and destructive checks.

API access

Yardstick exposes a public REST API under /v1/* for programmatic candidate creation, applications, events, and audit log access. Org admins mint tokens (publishable ys_pk_… for browsers, secret ys_sk_… for servers; both come in _test_ and _live_ modes) from /settings/api-tokens.

• API quickstart — rendered at /docs/api/quickstart; covers minting a token, the first request, and pagination.
• Full reference — rendered at /docs/api, powered by Scalar over the OpenAPI 3.1 document at /v1/openapi.json.
• Implementation skeleton — for engineers adding a new resource: per-request pipeline, env vars, test fixtures, and a checklist for new functions.

Yardstick CLI package

The npm package identity is @yardstick/cli and it exposes one binary: yardstick. It intentionally does not expose a default ys alias because that name can collide with YAMLScript tooling. This first packaged slice is macOS-only for local secure storage and uses macOS Keychain profiles.

Install the package and use the remote Yardstick API service by default:

npm install -g @yardstick/cli
yardstick login --mode test --label "Local agent"
yardstick whoami
yardstick tasks list --limit 25
yardstick status
yardstick logout

Packaged login opens https://portal.yardstick.team for approval. Without --scopes, it requests the current secret scope catalog with the configured default scopes preselected; pass --scopes to request a narrower set. Packaged read commands default to api-origin at https://api.yardstick.team. Local or raw Supabase fallback targets require explicit read-command flags such as --endpoint-mode supabase-functions and --base-url.

CI and other noninteractive shells may set YARDSTICK_API_TOKEN explicitly, but copied tokens and plaintext credential files are not the normal local interactive flow.

Repository-local package validation:

npm run build:cli
npm pack --dry-run
npm run package:cli:validate
npm run package:cli:smoke

npm run package:cli:smoke packs the CLI, installs it into a temporary prefix, and verifies the installed yardstick binary without using a repository checkout or tsx.

Documentation

• CI/CD Workflows
• Migration Guide
• Security Documentation
• Development Guide

Contributing

Please read our contributing guidelines before submitting pull requests.

License

[License information]

Support

For issues and questions:

• Create an issue in GitHub
• Contact the team via Slack channels mentioned in workflow documentation