linkedin-apply-assistant 0.1.1

package/SECURITY.md

@@ -0,0 +1,37 @@
+# Security Policy
+
+## Reporting Vulnerabilities
+
+Use GitHub private vulnerability reporting for the standalone project when available.
+
+If private reporting is not configured yet, open a maintainer-private channel before sharing exploit details publicly. A standalone security contact can be added here when the public repository is configured.
+
+Do not use upstream personal contacts as the default standalone package security contact.
+
+## Reporting Routes
+
+- Usage and setup support belongs in [SUPPORT.md](SUPPORT.md).
+- Public safety/compliance concerns can use [.github/ISSUE_TEMPLATE/safety_compliance.yml](.github/ISSUE_TEMPLATE/safety_compliance.yml) only without exploit details.
+- Conduct reports belong in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and should use private reporting.
+- Vulnerability details stay in this security policy and should not be posted publicly.
+
+## What to Report
+
+Report issues such as:
+
+- credential or token exposure
+- browser profile leakage
+- report redaction failures
+- unsafe submit behavior
+- dependency vulnerabilities
+- documentation that encourages unsafe platform behavior
+
+## Local Secret and Browser Profile Safety
+
+Keep local config, Q&A banks, visible-browser profiles, outputs, reports, and private documents out of version control. The package `.gitignore` contains the expected local runtime patterns.
+
+Never attach browser profiles, cookies, credentials, screenshots, private documents, generated local reports, or full private URLs to public issues.
+
+## Supported Versions
+
+The initial standalone GitHub source release is `0.1.0`. Current package metadata is `0.1.1`. Security guidance applies to the current unreleased, `0.1.1`, and `0.1.0` package-local surfaces.

package/SUPPORT.md

@@ -0,0 +1,44 @@
+# Support
+
+LinkedIn-apply-assistant support is for the standalone local package and its
+documented source, Python, and npm launcher workflows.
+
+## Before Opening an Issue
+
+Start with [README.md](README.md) and
+[docs/troubleshooting.md](docs/troubleshooting.md). For setup questions, run:
+
+```powershell
+linkedin-apply-assistant config check
+```
+
+Use the config/help issue form only after removing private local details.
+
+## Public Support Routes
+
+- Reproducible bugs: open a GitHub issue with the sanitized command, package
+  version or source commit, operating system, Python version, expected result,
+  actual result, and minimal reproduction steps.
+- Feature requests: describe the problem, proposed behavior, workflow impact,
+  safety/privacy impact, and alternatives considered.
+- Documentation issues: name the affected page or link, explain what is stale
+  or confusing, and suggest the correction.
+
+GitHub Discussions are not enabled for this repository in Phase 26.
+
+## Sensitive Routes
+
+- Vulnerabilities belong in [SECURITY.md](SECURITY.md). Do not post exploit
+  details publicly.
+- Safety or platform-compliance concerns can use the safety/compliance issue
+  form only when the concern can be described without exploit details or private
+  data.
+- Conduct reports belong in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) and should
+  use a maintainer-private channel placeholder until a dedicated private contact
+  is configured.
+
+## Do Not Post Private Data
+
+Do not post credentials, cookies, browser profiles, screenshots, CVs, private
+documents, generated local reports, full private URLs, or live job history in
+public issues, pull requests, or discussions.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,67 @@
+# Third-Party Notices
+
+This file records attribution and notice information for the standalone package. It is an engineering notice artifact, not legal advice.
+
+## Career-Ops
+
+Some implementation and documentation history was extracted from or derived from Career-Ops, an MIT-licensed project by Santiago Fernandez de Valderrama.
+
+Career-Ops is mentioned here only for neutral attribution and provenance. LinkedIn-apply-assistant is the standalone package identity.
+
+MIT notice:
+
+```text
+MIT License
+
+Copyright (c) 2026 Santiago Fernandez de Valderrama
+
+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.
+```
+
+## Scrapling
+
+Scrapling is a normal Python dependency of this package. It is not the product identity and is not an endorsement claim.
+
+License verification source checked during Phase 18 execution: official upstream repository license at `https://raw.githubusercontent.com/D4Vinci/Scrapling/main/LICENSE`. The upstream license identifies Scrapling as BSD 3-Clause, copyright 2024 Karim shoair.
+
+BSD 3-Clause notice:
+
+```text
+BSD 3-Clause License
+
+Copyright (c) 2024, Karim shoair
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+

package/bin/linkedin-apply-assistant.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, delimiter, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const cliModule = "linkedin_apply_assistant.cli";
+const userArgs = process.argv.slice(2);
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(scriptDir, "..");
+const localSrc = resolve(scriptDir, "..", "src");
+const launcherEnv = { ...process.env };
+const candidates =
+  process.platform === "win32"
+    ? [
+        ["py", ["-3"]],
+        ["python", []],
+        ["python3", []],
+      ]
+    : [
+        ["python3", []],
+        ["python", []],
+      ];
+
+if (existsSync(localSrc)) {
+  launcherEnv.PYTHONPATH = launcherEnv.PYTHONPATH
+    ? `${localSrc}${delimiter}${launcherEnv.PYTHONPATH}`
+    : localSrc;
+}
+
+function printSetupGuidance(reason) {
+  console.error(`linkedin-apply-assistant npm launcher could not start: ${reason}`);
+  console.error("");
+  console.error("This npm package is only a thin launcher for the Python package.");
+  console.error("Install the bundled Python package from this npm package root, then retry:");
+  console.error(`  python -m pip install "${packageRoot}"`);
+  console.error(`  py -3 -m pip install "${packageRoot}"`);
+  console.error("");
+  console.error("Module fallback after source checkout:");
+  console.error("  python -m linkedin_apply_assistant.cli --help");
+}
+
+function runPython(command, args, options = {}) {
+  return spawnSync(command, args, {
+    env: launcherEnv,
+    windowsHide: true,
+    ...options,
+  });
+}
+
+let sawPython = false;
+
+for (const [command, prefixArgs] of candidates) {
+  const probe = runPython(command, [...prefixArgs, "-c", `import ${cliModule}`], {
+    stdio: "ignore",
+  });
+
+  if (probe.error?.code === "ENOENT") {
+    continue;
+  }
+
+  if (probe.error) {
+    continue;
+  }
+
+  sawPython = true;
+
+  if (probe.status !== 0) {
+    continue;
+  }
+
+  const result = runPython(command, [...prefixArgs, "-m", cliModule, ...userArgs], {
+    stdio: "inherit",
+  });
+
+  if (result.error) {
+    printSetupGuidance(result.error.message);
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    console.error(`Python CLI exited after signal ${result.signal}`);
+    process.exit(1);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+printSetupGuidance(
+  sawPython
+    ? "Python was found, but the linkedin_apply_assistant package is not importable."
+    : "No usable Python executable was found on PATH.",
+);
+process.exit(1);

package/configs/config.example.yml

@@ -0,0 +1,24 @@
+profile:
+  name: "Example Candidate"
+  headline: "Software engineer"
+  location: "Example City"
+  contact:
+    email: "candidate@example.com"
+    phone: null
+    website: "https://example.com/portfolio"
+
+defaults:
+  limit: 10
+  visible_browser: true
+  require_confirmation: true
+  dry_run: true
+
+documents:
+  resume: "documents/resume.example.pdf"
+  cover_letter: "documents/cover-letter.example.pdf"
+  portfolio: "https://example.com/portfolio"
+
+paths:
+  qa_bank: "configs/qa_bank.example.yml"
+  browser_profile: null
+  output_dir: "local-output"

package/configs/qa_bank.example.yml

@@ -0,0 +1,35 @@
+qa_pairs:
+  - id: work_authorization
+    question_patterns:
+      - "Are you authorized to work in the target country?"
+      - "Do you require sponsorship?"
+    answer: "Use a truthful work-authorization answer for your situation."
+    response_type: text
+
+  - id: notice_period
+    question_patterns:
+      - "When can you start?"
+      - "What is your notice period?"
+    answer: "Use your current availability or notice period."
+    response_type: text
+
+  - id: work_arrangement
+    question_patterns:
+      - "Do you prefer remote, hybrid, or onsite work?"
+      - "What work arrangement are you looking for?"
+    answer: "Remote or hybrid roles are preferred, depending on team needs."
+    response_type: text
+
+  - id: compensation_expectation
+    question_patterns:
+      - "What are your salary expectations?"
+      - "What compensation range are you targeting?"
+    answer: "Use a realistic range for the role, location, and market."
+    response_type: text
+
+  - id: portfolio
+    question_patterns:
+      - "Please share a portfolio or project link."
+      - "Do you have examples of your work?"
+    answer: "https://example.com/portfolio"
+    response_type: url

package/docs/apply.md

@@ -0,0 +1,40 @@
+# Prepare-Only Apply Workflow
+
+`apply` prepares local application audit output from candidate job input. Browser submission remains disabled in the current public package.
+
+## Prepare From Input
+
+Use synthetic or local candidate job input:
+
+```powershell
+linkedin-apply-assistant apply --input examples\dry_run_input.example.json --limit 1
+```
+
+The input file should not contain credentials, private documents, browser state, screenshots, full private URLs, or live job history.
+
+## Guarded Future Option
+
+The CLI exposes `--confirm-submit` as a guarded future option:
+
+```powershell
+linkedin-apply-assistant apply --input examples\dry_run_input.example.json --limit 1 --confirm-submit
+```
+
+Current browser submission remains disabled. Any future submit-capable release must still require explicit per-submission confirmation immediately before a specific application is sent, and must preserve the safety guardrails described in [../SAFETY.md](../SAFETY.md).
+
+## Shared Options
+
+`apply` accepts:
+
+- `--workspace`
+- `--config`
+- `--qa-bank`
+- `--browser-profile`
+- `--output-dir`
+- `--verbose`
+- `--input`
+- `--limit`
+- `--confirm-submit`
+
+Do not use `apply` for mass applications, unattended apply sessions, fake answers, CAPTCHA or MFA bypass, or continued automation after platform risk signals.
+

package/docs/assist.md

@@ -0,0 +1,35 @@
+# Assistive Fill-Only Workflow
+
+`assist` opens a visible-browser workflow where the user drives the session and the assistant fills supported fields. It is a fill-only boundary.
+
+## On-Demand Mode
+
+Use on-demand mode when you want to control each fill attempt:
+
+```powershell
+linkedin-apply-assistant assist --mode on-demand --max-cycles 3
+```
+
+## Auto-Watch Mode
+
+Use auto-watch when you want the assistant to inspect detected fillable surfaces:
+
+```powershell
+linkedin-apply-assistant assist --mode auto-watch --max-cycles 3
+```
+
+## Start Page
+
+```powershell
+linkedin-apply-assistant assist --start-url "https://www.linkedin.com/jobs/" --mode on-demand
+```
+
+## Boundaries
+
+- You remain responsible for the browser session.
+- Unknown required questions should stop until you provide a truthful answer.
+- The assistant must not submit applications in this workflow.
+- The assistant must not continue through CAPTCHA, MFA, checkpoints, platform throttling, or similar risk signals.
+
+For browser profile safety, see [browser-session.md](browser-session.md).
+

package/docs/browser-session.md

@@ -0,0 +1,45 @@
+# Visible Browser Session Setup
+
+Browser workflows are local and user-visible. You drive or review the browser session; the package does not run hidden unattended apply workflows.
+
+## Browser Profile
+
+Use `--browser-profile` to choose a local profile directory:
+
+```powershell
+linkedin-apply-assistant --browser-profile .\local-workspace\browser-profile assist --mode on-demand
+```
+
+The profile can contain cookies, sessions, and local form state. Keep it ignored, local, and under your control. Do not copy it into examples, issues, fixtures, or reports.
+
+## Login Flow
+
+Open a visible browser session and log in yourself when the platform asks for it. If a checkpoint, rate limit, MFA prompt, or other platform risk signal appears, stop and resolve it manually.
+
+The assistant must not bypass CAPTCHA, MFA, checkpoints, platform throttling, or employer application rules.
+
+## Start URL
+
+Use `assist --start-url` when you want the visible browser to open a specific starting page:
+
+```powershell
+linkedin-apply-assistant assist --start-url "https://www.linkedin.com/jobs/" --mode on-demand
+```
+
+Only use URLs you are comfortable opening in your own browser session. Do not publish full private application URLs in docs or examples.
+
+## Session Modes
+
+`assist` supports:
+
+- `--mode on-demand`: inspect/fill only when requested by the user workflow.
+- `--mode auto-watch`: watch for fillable surfaces and fill once per detected surface.
+
+Example:
+
+```powershell
+linkedin-apply-assistant assist --mode auto-watch --max-cycles 3
+```
+
+Both modes remain fill-only boundaries. They do not submit applications.
+

package/docs/ci-and-release-policy.md

@@ -0,0 +1,105 @@
+# CI and Release Policy
+
+This repository uses CI to make public project health visible without creating
+tags, GitHub Releases, package uploads, registry tokens, attestations, or
+repository-setting changes.
+
+## Workflows
+
+Two user-authored GitHub Actions workflows are expected on `main`:
+
+- `Quality` at `.github/workflows/quality.yml`
+- `Security` at `.github/workflows/security.yml`
+
+Both workflows run on pull requests, pushes to `main`, and manual dispatch. Only
+`Security` has a weekly scheduled scan. Both workflows use concurrency with
+`cancel-in-progress` so stale branch runs do not consume runner capacity.
+
+## Quality
+
+The `Quality` workflow has two jobs:
+
+- `quality` runs on Ubuntu with Python `3.11` and `3.12`.
+- `release-smoke` runs once with Python `3.12` and Node.js `24`.
+
+The workflow installs Python dependencies with:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+It does not require `npm ci` because the package does not currently ship a
+standalone lockfile. The release-smoke job validates the release manifest, runs
+focused release-readiness tests, runs `python scripts/release.py verify`, and
+checks npm launcher package shape with `npm pack --dry-run --json`.
+
+The CI suite intentionally stays browser-free. It does not run live LinkedIn,
+browser-profile, final-submit, or user-layer-file workflows.
+
+## Security
+
+The `Security` workflow has three jobs:
+
+- `codeql` runs committed CodeQL advanced setup for Python and JavaScript only,
+  with `security-extended` queries.
+- `dependency-review` runs only on pull requests and fails on high or critical
+  dependency risk through `fail-on-severity: high`.
+- `secret-scan` runs Gitleaks against the checked-out repository history.
+
+Workflow permissions default to `contents: read`. The only write permission is
+`security-events: write`, and it is limited to the CodeQL job.
+The Gitleaks step receives the default `GITHUB_TOKEN` only for action API access
+and sets `GITLEAKS_ENABLE_COMMENTS=false`, so it does not need pull-request write
+permissions.
+
+Phase 28 deliberately does not add Bandit, Semgrep, or another extra SAST tool.
+Dependabot covers GitHub Actions, npm, and pip at repository root `/` with
+weekly grouped updates, open pull request limit `5`, and no auto-merge. Labels
+and assignees are skipped unless maintainers add a label policy later.
+
+## Release Automation Boundary
+
+This project currently uses manual GitHub source releases. Phase 28 does not
+enable Release Please, semantic-release, tag automation, changelog automation,
+or any equivalent release writer.
+
+Conventional Commits are recommended for maintainability, but CI does not
+enforce commit-message format.
+
+The workflows and Dependabot config are source-release metadata. They are kept
+in `release-manifest.json` for source-checkout visibility, but workflow files
+and `.github/dependabot.yml` are excluded from npm package contents unless a
+future phase intentionally documents otherwise.
+
+## Deferred Provenance Work
+
+The following controls are feasible future work, not active behavior:
+
+- SBOM generation, after a real artifact channel is selected.
+- Artifact attestations, after the project intentionally grants
+  `id-token: write` and `attestations: write`.
+- Signing and immutable-release policy, after release assets or package
+  channels exist.
+- Trusted publisher setup or package-name reservation, in a dedicated registry
+  publication phase.
+
+The future registry channel order, trusted-publishing boundary, approval
+templates, and rollback limits are documented in the
+[registry publication strategy](registry-publication-strategy.md).
+
+No Phase 28 workflow grants `packages: write`, `id-token: write`, or
+`attestations: write`.
+
+## No-Surprise Publish Boundary
+
+Phase 28 automation must not:
+
+- run `npm publish`
+- run `twine upload`
+- create, edit, delete, or upload a GitHub Release
+- create or push tags
+- reserve package names
+- configure trusted publishers
+- mutate branch rulesets, tag rulesets, required checks, or repository settings
+
+Public sync and live workflow verification remain explicit maintainer actions.