@hadoku/jobplatform 0.0.0-stage → 3.41.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthaeus Wolff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,186 @@
-# Temporary Holding Version
+# hadoku-jobplatform
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An end-to-end job-search pipeline. It pulls postings off company ATS boards, scores
+them against role profiles you define, lets you triage what survives, and assembles a
+full application packet — tailored resume, cover letter, intro email, screening
+answers — for the ones worth applying to.
+
+Live at **[hadoku.me/jobplatform](https://hadoku.me/jobplatform)** (~7,600 postings in
+the corpus as of August 2026). The job list is public; profiles, triage state, and
+application packets need an account.
+
+This is one app in the [hadoku.me](https://hadoku.me) ecosystem — a personal platform
+where each app ships as an independently versioned npm package and gets mounted by a
+parent site. Nothing here runs standalone; see [How it fits together](#how-it-fits-together).
+
+---
+
+## The problem it solves
+
+Job boards rank by recency and their own incentives. Searching them means re-reading
+the same 200 postings weekly to find the four that changed. This inverts that: describe
+the role you want _once_, and every scrape run re-ranks the whole corpus against it.
+
+Three things make that non-trivial, and most of the interesting code is in the answers:
+
+**No ATS publishes seniority.** Not Greenhouse, not Lever, not Ashby. "Staff Engineer"
+vs "Engineering Manager" exists only in the title string. So role is inferred at ingest
+([`worker/src/roleClassify.ts`](worker/src/roleClassify.ts)) along **two orthogonal
+axes** rather than one list:
+
+- `track` — `ic` or `manager`. Answers "does this job have direct reports?"
+- `level` — the rung on that track's ladder.
+
+They're orthogonal because a flat list makes `senior` and `manager` look like
+alternatives to each other, which is nonsense — they're answers to different questions.
+Classification reads the _head_ of the title, before the first comma, so
+"Software Engineer, Ads Manager" correctly lands as an IC. Only the genuinely ambiguous
+`lead` family falls back to probing the description body.
+
+**Filtering and ranking are different requests.** "Only show me IC roles" is not "rank
+IC roles higher." Company, `track`, and salary floor are **hard SQL filters**; everything
+else is a weighted score. Conflating the two produces a feed that's technically sorted
+and practically useless.
+
+**Salary is mostly absent.** `salary_min` is NULL on most postings, so scoring it
+returned a neutral ~0.5 for nearly everything — pure noise dressed as signal. It was
+removed as a score factor and demoted to a view filter. Postings with no listed salary
+survive the filter, because hiding them would empty the feed rather than narrow it.
+
+### Scoring
+
+Runs on read, per request — so a score always reflects the profile as it is _now_
+rather than as it was when some batch job last ran. (The precomputed match table was
+dropped in migration 0008 for exactly this reason.)
+
+| Signal          | Weight | What it measures                            |
+| --------------- | -----: | ------------------------------------------- |
+| `keyword_match` |   0.40 | profile keywords against the description    |
+| `title_match`   |   0.30 | profile keywords against the title          |
+| `level_match`   |   0.15 | distance on the seniority ladder            |
+| `remote_match`  |   0.15 | remote / hybrid / onsite against preference |
+
+`level_match` grades by _distance_, not equality: exact rung 1.0, one rung off 0.7,
+further or off-track 0.2 — and an unclassified job scores 0.5, because no signal is not
+the same as a bad match. Full algorithm and data model:
+[`ARCHITECTURE.md`](./ARCHITECTURE.md).
+
+---
+
+## Architecture
+
+Two independently published packages live in this repo:
+
+| Package                      | Path      | What it is                                      |
+| ---------------------------- | --------- | ----------------------------------------------- |
+| `@wolffm/jobplatform`        | `src/`    | React micro-frontend, exports `mount`/`unmount` |
+| `@wolffm/jobplatform-worker` | `worker/` | Cloudflare Worker API (Hono + D1)               |
+
+The pipeline, end to end:
+
+```
+  Profile: keywords, track, levels, remote pref, companies
+    │
+    ▼
+  GET /directives ──────────► hadoku-scrape  (Python, separate repo)
+    the union of every            │  resolves company → (ats, slug)
+    profile's companies +         │  enumerates Greenhouse / Lever / LinkedIn
+    keywords. The scraper         │  archives raw postings to Cloudflare KV
+    PULLS this each run.          │
+                                  ▼
+                          POST /ingest   (full postings inline, batches of 25)
+                                  │
+                                  ▼
+                      ┌───────────────────────────┐
+                      │  jobplatform-worker       │
+                      │  • dedup by URL           │
+                      │  • classify track + level │
+                      │  • parse (ats, slug)      │
+                      │  • store in D1            │
+                      └───────────┬───────────────┘
+                                  │  score on read, per request
+                                  ▼
+                      ┌───────────────────────────┐
+                      │  jobplatform (React)      │
+                      │  • ranked feed + filters  │
+                      │  • triage: interested /   │
+                      │    saved / applied / …    │
+                      │  • job detail + breakdown │
+                      └───────────┬───────────────┘
+                                  │  service binding
+                                  ▼
+                            resume-api  →  resume, cover letter, intro email,
+                                           screening answers → one shareable packet
+```
+
+Companies are a **directive the scraper pulls**, not targets this app pushes. The worker
+publishes what it wants scraped at `GET /directives`; the scraper reads that on its next
+run and registers targets itself. That keeps registry ownership in one place — the
+scraper owns _how_ to scrape, this app owns _what_ is worth scraping.
+
+Full API table and design rationale: [`CLAUDE.md`](./CLAUDE.md).
+
+---
+
+## How it fits together
+
+```
+hadoku_site  (parent)
+  ├── mounts @wolffm/jobplatform          at  hadoku.me/jobplatform
+  └── hosts  @wolffm/jobplatform-worker   at  hadoku.me/jobplatform/api
+                                                │
+                            ┌───────────────────┼───────────────────┐
+                            ▼                   ▼                   ▼
+                       hadoku-scrape        resume-bot         Cloudflare D1
+                       (postings)        (resume/cover)      (scored corpus)
+```
+
+Push to `main` publishes both packages to GitHub Packages and fires a
+`packages_updated` dispatch; the parent site pulls the new versions and redeploys.
+
+Auth is tier-ranked (`public < friend < service < admin`), gated in-worker. The parent's
+edge router resolves a session cookie into a user key and stamps the tier; the worker
+trusts that stamp only when its provenance header verifies, so a request that bypasses
+the edge degrades to `public` rather than being trusted.
+
+---
+
+## Development
+
+Requires `pnpm`. The dev server needs secrets brokered from the parent repo, so a
+standalone clone will build and test but not fully run.
+
+```bash
+pnpm install
+
+pnpm dev          # dev server on :5173
+pnpm build        # build both packages
+pnpm lint         # eslint
+pnpm lint:css     # stylelint + theme-token check
+pnpm typecheck
+
+cd worker && pnpm test   # node:test, no framework
+```
+
+To act as an authenticated user in dev, pass `?apiKey=<key>` once — the harness in
+`index.html` exchanges it for a session id through the same code path production uses.
+The URL parameter is dev-only and never accepted in production.
+
+**Colors** come from `@wolffm/themes` as semantic CSS custom properties
+(`var(--color-primary)`, `var(--color-on-primary-bg)`, …). Light and dark are automatic;
+never branch on theme mode, and never hardcode a hex value. `pnpm lint:css` fails the
+build on a reference to a token the theme doesn't define — worth running, since an
+undefined token renders as nothing rather than erroring.
+
+**Logging** goes through the logger from `@wolffm/task-ui-components`, not `console.log`:
+
+```typescript
+import { logger } from '@wolffm/task-ui-components'
+logger.info('Message', { key: 'value' })
+```
+
+---
+
+## License
+
+[MIT](./LICENSE).

package/dist/App.d.ts

@@ -0,0 +1,9 @@
+import type { JobPlatformProps } from './entry';
+/**
+ * Provider boundary. Theme state belongs to the platform (@wolffm/themes),
+ * not to this app — the local hooks/useTheme.ts, prefs/themePrefs.ts and
+ * app/themeConfig.tsx copies are gone. AppHeader renders the shared picker
+ * from this context, so nothing below passes one.
+ */
+export default function App(props?: JobPlatformProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=App.d.ts.map

package/dist/App.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../src/App.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAS/C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,GAAG,CAAC,KAAK,GAAE,gBAAqB,2CAOvD"}

package/dist/api/applyQueue.d.ts

@@ -0,0 +1,42 @@
+import type { Auth } from './auth';
+/** Where one job is in the sequence. `error` carries a reason; the rest don't. */
+export type ApplyPhase = 'idle' | 'waiting' | 'preparing' | 'queueing' | 'queued' | 'error';
+export interface ApplyStatus {
+    phase: ApplyPhase;
+    error?: string;
+}
+/**
+ * Run the whole sequence for one job and return the packet slug.
+ *
+ * The two generation calls are SEQUENCED, not concurrent. The résumé is the
+ * token-heavy one (block selection + rewrite), so it runs alone; then a single
+ * application-extras call returns the cover letter and the rest of the kit
+ * together. Firing the cover letter and the extras as separate back-to-back
+ * calls used to stack past Groq's per-minute token cap so the trailing one
+ * 500'd, leaving a packet with a résumé and no kit.
+ */
+export declare function prepareApplicationPacket(jobId: string, auth: Auth, onPhase?: (phase: ApplyPhase) => void): Promise<{
+    slug: string;
+    url: string;
+    resume: string;
+    coverLetter: string;
+}>;
+/**
+ * Handing a posting to the runner is now ONE request.
+ *
+ * It used to be four: résumé, kit, mint, queue — about 21 seconds of LLM work
+ * per posting, run in this tab behind a one-at-a-time lane so the generations
+ * could not stack past the per-minute token cap. That made a click look
+ * accepted while nothing durable existed. Queueing eight postings meant the
+ * last began two and a half minutes later, and closing the tab, reloading, or
+ * switching to Applications discarded everything the lane had not reached —
+ * along with every error, so there was no record the owner had ever asked.
+ *
+ * `POST /jobs/:id/apply` no longer needs a minted packet. The row is written
+ * immediately and the runner mints the packet just before it fills, so the
+ * click is a single fast write that survives the tab. The lane is gone with
+ * the work it was protecting.
+ */
+/** Hand one posting to the runner. One request, durable the moment it returns. */
+export declare function enqueueApply(jobId: string, auth: Auth, onStatus: (status: ApplyStatus) => void): Promise<void>;
+//# sourceMappingURL=applyQueue.d.ts.map

package/dist/api/applyQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"applyQueue.d.ts","sourceRoot":"","sources":["../../src/api/applyQueue.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAA;AAElC,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE3F,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GACpC,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CA6B7E;AAED;;;;;;;;;;;;;;;GAeG;AAEH,kFAAkF;AAClF,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,GACtC,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/api/auth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Who the parent app (hadoku_site) says is looking at this MFE.
+ *
+ * The credential never enters the bundle. A same-origin `fetch` carries the
+ * HttpOnly `hadoku_session` cookie on its own, and edge-router resolves it
+ * into `X-User-Key` for the worker. The session id used to arrive here as a
+ * prop and go out as `X-Session-Id`, which let page JavaScript read a 30-day
+ * bearer credential (hadoku_site#459) — so all this carries is whether anyone
+ * is signed in, from mf-loader's `userType` prop.
+ */
+export interface Auth {
+    signedIn: boolean;
+}
+export declare function authHeaders(_auth?: Auth, json?: boolean): HeadersInit;
+//# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/api/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,WAAW,IAAI;IACnB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,wBAAgB,WAAW,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,IAAI,UAAQ,GAAG,WAAW,CAInE"}

package/dist/api/companies.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Company lookups behind the profile "add company" flow.
+ * Subscriptions themselves live per-profile — see api/profiles.ts.
+ * Auth model: see `./auth.ts`.
+ */
+import { type Auth } from './auth';
+export interface CompanyMatch {
+    query: string;
+    matched: boolean;
+    ats: string | null;
+    slug: string | null;
+    company_name: string | null;
+    n_jobs: number;
+    sample_titles: string[];
+    domain: string | null;
+}
+export declare class CompaniesApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+/**
+ * Name-driven prefetch: type company names, get the single best board each
+ * (most open jobs) to confirm before adding to a profile. Read-only.
+ */
+export declare function matchCompanies(names: string[], auth?: Auth): Promise<CompanyMatch[]>;
+//# sourceMappingURL=companies.d.ts.map

package/dist/api/companies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"companies.d.ts","sourceRoot":"","sources":["../../src/api/companies.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAe,KAAK,IAAI,EAAE,MAAM,QAAQ,CAAA;AAW/C,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;IAChB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAGjC,MAAM,EAAE,MAAM;gBADrB,OAAO,EAAE,MAAM,EACR,MAAM,EAAE,MAAM;CAKxB;AAaD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAS1F"}