linkedin-apply-assistant 0.1.1

package/docs/troubleshooting.md

@@ -0,0 +1,57 @@
+# Troubleshooting
+
+Start with the command help:
+
+```powershell
+linkedin-apply-assistant --help
+linkedin-apply-assistant config check
+linkedin-apply-assistant config check --help
+linkedin-apply-assistant search --help
+linkedin-apply-assistant assist --help
+linkedin-apply-assistant apply --help
+linkedin-apply-assistant dry-run --help
+linkedin-apply-assistant report --help
+```
+
+For normal command examples, resolved output paths, reports, browser profile location, and first-run setup, read the [command reference](commands.md).
+
+## Command Not Found
+
+Install the package in editable mode:
+
+```powershell
+python -m pip install -e ".[dev]"
+```
+
+Or use the module fallback:
+
+```powershell
+$env:PYTHONPATH=(Resolve-Path 'src').Path
+python -m linkedin_apply_assistant.cli --help
+```
+
+## Browser Does Not Open
+
+- Confirm Playwright is installed with the package dependencies.
+- Install Chromium with `python -m playwright install chromium`.
+- Run `linkedin-apply-assistant config check` to inspect the resolved browser profile path.
+- Use `--browser-profile` with a local ignored directory.
+- Avoid copying browser profile directories between machines or into public artifacts.
+
+## Unknown Required Questions
+
+Update your local Q&A bank from [../configs/qa_bank.example.yml](../configs/qa_bank.example.yml). Unknown required questions should pause the workflow until you can provide a truthful answer.
+
+## Selector Drift
+
+LinkedIn and ATS pages can change. If a visible-browser workflow stops detecting fields, reduce scope to `dry-run` or `report`, capture a sanitized description, and add or update tests before changing selectors.
+
+## Quality Gate Failure
+
+Run the package quality gate from the package root:
+
+```powershell
+python scripts\quality.py
+```
+
+The gate runs compile checks, package pytest, Ruff check, Ruff format check, dependency audit, docs smoke tests, privacy scans, and release-readiness checks.

package/examples/dry_run_input.example.json

@@ -0,0 +1,25 @@
+{
+  "jobs": [
+    {
+      "title": "Backend Platform Engineer",
+      "company": "Example Systems",
+      "url": "https://example.com/jobs/backend-platform-engineer",
+      "location": "Remote",
+      "description": "Build and maintain service APIs, data workflows, and reliability tooling for a small product team."
+    },
+    {
+      "title": "Frontend Application Engineer",
+      "company": "Sample Interface Labs",
+      "url": "https://example.com/jobs/frontend-application-engineer",
+      "location": "Example City",
+      "description": "Develop accessible application screens, reusable components, and browser-based workflow improvements."
+    },
+    {
+      "title": "Automation QA Engineer",
+      "company": "Demo Quality Works",
+      "url": "https://example.com/jobs/automation-qa-engineer",
+      "location": "Hybrid",
+      "description": "Create deterministic test fixtures, validate user-facing flows, and improve local developer feedback loops."
+    }
+  ]
+}

package/examples/reports/apply-audit.example.json

@@ -0,0 +1,31 @@
+{
+  "schema_version": "example-1",
+  "command": "apply",
+  "generated_at": "2026-06-08T00:00:00Z",
+  "status": "prepared",
+  "summary": {
+    "jobs_loaded": 1,
+    "jobs_prepared": 1,
+    "applications_submitted": 0,
+    "unknown_required_questions": 1
+  },
+  "jobs": [
+    {
+      "company": "Example Robotics",
+      "role": "Applied AI Engineer",
+      "decision": "needs-review",
+      "submit_state": "disabled",
+      "blockers": [
+        "One required question needs a truthful user answer before completion."
+      ]
+    }
+  ],
+  "privacy": {
+    "synthetic": true,
+    "contains_browser_state": false,
+    "contains_private_documents": false,
+    "contains_full_private_urls": false,
+    "contains_screenshots": false
+  }
+}
+

package/examples/reports/search-report.example.json

@@ -0,0 +1,40 @@
+{
+  "schema_version": "example-1",
+  "command": "search",
+  "generated_at": "2026-06-08T00:00:00Z",
+  "status": "completed",
+  "query": {
+    "text": "applied ai engineer",
+    "location": "Remote",
+    "limit": 2
+  },
+  "summary": {
+    "jobs_seen": 2,
+    "jobs_recorded": 2,
+    "applications_submitted": 0,
+    "blocked": 0
+  },
+  "jobs": [
+    {
+      "company": "Example Robotics",
+      "role": "Applied AI Engineer",
+      "source": "linkedin-search",
+      "status": "recorded",
+      "public_domain": "example.test"
+    },
+    {
+      "company": "Sample Automation Lab",
+      "role": "Workflow Automation Engineer",
+      "source": "linkedin-search",
+      "status": "recorded",
+      "public_domain": "example.test"
+    }
+  ],
+  "privacy": {
+    "synthetic": true,
+    "contains_browser_state": false,
+    "contains_private_documents": false,
+    "contains_full_private_urls": false
+  }
+}
+

package/install.ps1

@@ -0,0 +1,178 @@
+[CmdletBinding()]
+param(
+    [string]$InstallDir = (Join-Path $env:LOCALAPPDATA "linkedin-apply-assistant"),
+    [string]$Ref = "main",
+    [switch]$InstallBrowser,
+    [switch]$NoPath
+)
+
+Set-StrictMode -Version 3.0
+$ErrorActionPreference = "Stop"
+
+$RepoOwner = "MohammedGhazal09"
+$RepoName = "linkedin-apply-assistant"
+
+function Write-Step {
+    param([string]$Message)
+    Write-Host "[linkedin-apply-assistant] $Message"
+}
+
+function Get-ArchiveUrl {
+    param([string]$SourceRef)
+
+    if ($SourceRef -match "^refs/heads/") {
+        return "https://github.com/$RepoOwner/$RepoName/archive/$SourceRef.zip"
+    }
+    if ($SourceRef -match "^refs/tags/") {
+        return "https://github.com/$RepoOwner/$RepoName/archive/$SourceRef.zip"
+    }
+    if ($SourceRef -match "^v?\d+\.\d+\.\d+") {
+        return "https://github.com/$RepoOwner/$RepoName/archive/refs/tags/$SourceRef.zip"
+    }
+    return "https://github.com/$RepoOwner/$RepoName/archive/refs/heads/$SourceRef.zip"
+}
+
+function Get-Python {
+    $candidates = @(
+        @{ Command = "py"; Args = @("-3.11") },
+        @{ Command = "py"; Args = @("-3") },
+        @{ Command = "python"; Args = @() },
+        @{ Command = "python3"; Args = @() }
+    )
+
+    foreach ($candidate in $candidates) {
+        $command = $candidate.Command
+        $prefixArgs = [string[]]$candidate.Args
+        try {
+            & $command @prefixArgs -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 11) else 1)" *> $null
+            if ($LASTEXITCODE -eq 0) {
+                return $candidate
+            }
+        }
+        catch {
+            continue
+        }
+    }
+
+    throw "Python 3.11 or newer was not found. Install Python 3.11+ and rerun this script."
+}
+
+function Invoke-Python {
+    param(
+        [hashtable]$Python,
+        [string[]]$Arguments
+    )
+
+    & $Python.Command @([string[]]$Python.Args + $Arguments)
+    if ($LASTEXITCODE -ne 0) {
+        throw "Python command failed: $($Python.Command) $($Arguments -join ' ')"
+    }
+}
+
+function Add-UserPathEntry {
+    param([string]$PathEntry)
+
+    $current = [Environment]::GetEnvironmentVariable("Path", "User")
+    $parts = @()
+    if ($current) {
+        $parts = $current -split [IO.Path]::PathSeparator
+    }
+    if ($parts -contains $PathEntry) {
+        return
+    }
+
+    $next = if ($current) {
+        "$PathEntry$([IO.Path]::PathSeparator)$current"
+    }
+    else {
+        $PathEntry
+    }
+    [Environment]::SetEnvironmentVariable("Path", $next, "User")
+
+    if (($env:Path -split [IO.Path]::PathSeparator) -notcontains $PathEntry) {
+        $env:Path = "$PathEntry$([IO.Path]::PathSeparator)$env:Path"
+    }
+}
+
+$python = Get-Python
+$archiveUrl = Get-ArchiveUrl -SourceRef $Ref
+$installRoot = [IO.Path]::GetFullPath($InstallDir)
+$sourceDir = Join-Path $installRoot "source"
+$venvDir = Join-Path $installRoot ".venv"
+$binDir = Join-Path $installRoot "bin"
+$tempDir = Join-Path ([IO.Path]::GetTempPath()) ("linkedin-apply-assistant-" + [guid]::NewGuid())
+$zipPath = Join-Path $tempDir "source.zip"
+
+try {
+    Write-Step "Installing from $archiveUrl"
+    New-Item -ItemType Directory -Force -Path $tempDir | Out-Null
+    New-Item -ItemType Directory -Force -Path $installRoot | Out-Null
+
+    Invoke-WebRequest -UseBasicParsing -Uri $archiveUrl -OutFile $zipPath
+    Expand-Archive -LiteralPath $zipPath -DestinationPath $tempDir -Force
+
+    $expanded = Get-ChildItem -LiteralPath $tempDir -Directory |
+        Where-Object { $_.Name -like "$RepoName-*" } |
+        Select-Object -First 1
+    if ($null -eq $expanded) {
+        throw "Could not find extracted package directory in $tempDir"
+    }
+
+    if (Test-Path -LiteralPath $sourceDir) {
+        Remove-Item -LiteralPath $sourceDir -Recurse -Force
+    }
+    Move-Item -LiteralPath $expanded.FullName -Destination $sourceDir
+
+    Write-Step "Creating virtual environment"
+    Invoke-Python -Python $python -Arguments @("-m", "venv", $venvDir)
+
+    $venvPython = Join-Path $venvDir "Scripts\python.exe"
+    if (-not (Test-Path -LiteralPath $venvPython)) {
+        throw "Virtual environment Python was not created at $venvPython"
+    }
+
+    Write-Step "Installing Python package"
+    & $venvPython -m pip install --upgrade pip
+    if ($LASTEXITCODE -ne 0) { throw "pip upgrade failed" }
+    & $venvPython -m pip install $sourceDir
+    if ($LASTEXITCODE -ne 0) { throw "Package install failed" }
+
+    if ($InstallBrowser) {
+        Write-Step "Installing Playwright Chromium"
+        & $venvPython -m playwright install chromium
+        if ($LASTEXITCODE -ne 0) { throw "Playwright Chromium install failed" }
+    }
+
+    New-Item -ItemType Directory -Force -Path $binDir | Out-Null
+    $psShim = Join-Path $binDir "linkedin-apply-assistant.ps1"
+    $cmdShim = Join-Path $binDir "linkedin-apply-assistant.cmd"
+
+    @"
+param([Parameter(ValueFromRemainingArguments = `$true)][string[]]`$RemainingArgs)
+& "$venvPython" -m linkedin_apply_assistant.cli @RemainingArgs
+exit `$LASTEXITCODE
+"@ | Set-Content -LiteralPath $psShim -Encoding UTF8
+
+    "@echo off`r`n`"$venvPython`" -m linkedin_apply_assistant.cli %*`r`n" |
+        Set-Content -LiteralPath $cmdShim -Encoding ASCII
+
+    if (-not $NoPath) {
+        Add-UserPathEntry -PathEntry $binDir
+    }
+
+    Write-Step "Installed to $installRoot"
+    Write-Host ""
+    Write-Host "Try it now:"
+    Write-Host "  linkedin-apply-assistant --help"
+    Write-Host "  linkedin-apply-assistant config check"
+    if (-not $InstallBrowser) {
+        Write-Host ""
+        Write-Host "For visible-browser workflows, install Chromium later with:"
+        Write-Host "  & `"$venvPython`" -m playwright install chromium"
+    }
+}
+finally {
+    if (Test-Path -LiteralPath $tempDir) {
+        Remove-Item -LiteralPath $tempDir -Recurse -Force
+    }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "linkedin-apply-assistant",
+  "version": "0.1.1",
+  "description": "Thin npm launcher for the Python LinkedIn apply assistant package",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MohammedGhazal09/linkedin-apply-assistant.git"
+  },
+  "homepage": "https://github.com/MohammedGhazal09/linkedin-apply-assistant#readme",
+  "bugs": {
+    "url": "https://github.com/MohammedGhazal09/linkedin-apply-assistant/issues"
+  },
+  "type": "module",
+  "bin": {
+    "linkedin-apply-assistant": "bin/linkedin-apply-assistant.mjs"
+  },
+  "files": [
+    "bin/linkedin-apply-assistant.mjs",
+    "pyproject.toml",
+    "src/",
+    "install.ps1",
+    "README.md",
+    "SAFETY.md",
+    "LEGAL.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md",
+    "CHANGELOG.md",
+    "MIGRATION.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "SUPPORT.md",
+    "GOVERNANCE.md",
+    "CODE_OF_CONDUCT.md",
+    ".github/ISSUE_TEMPLATE/bug_report.yml",
+    ".github/ISSUE_TEMPLATE/feature_request.yml",
+    ".github/ISSUE_TEMPLATE/docs.yml",
+    ".github/ISSUE_TEMPLATE/safety_compliance.yml",
+    ".github/ISSUE_TEMPLATE/config_help.yml",
+    ".github/ISSUE_TEMPLATE/config.yml",
+    ".github/PULL_REQUEST_TEMPLATE.md",
+    "RELEASE_CHECKLIST.md",
+    "docs/install-and-configuration.md",
+    "docs/registry-publication-strategy.md",
+    "docs/commands.md",
+    "docs/browser-session.md",
+    "docs/search.md",
+    "docs/assist.md",
+    "docs/apply.md",
+    "docs/ci-and-release-policy.md",
+    "docs/reports.md",
+    "docs/troubleshooting.md",
+    "configs/config.example.yml",
+    "configs/qa_bank.example.yml",
+    "examples/dry_run_input.example.json",
+    "examples/reports/search-report.example.json",
+    "examples/reports/apply-audit.example.json"
+  ]
+}

package/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "linkedin-apply-assistant"
+version = "0.1.1"
+description = "Local LinkedIn application assistant with user-visible browser workflows"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+  "playwright>=1.40",
+  "scrapling>=0.2.0",
+  "PyYAML>=6.0",
+  "platformdirs>=4.0",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=9.0.3"]
+dev = [
+  "build>=1.0",
+  "pip-audit>=2.7",
+  "pytest>=9.0.3",
+  "ruff>=0.6",
+]
+
+[project.scripts]
+linkedin-apply-assistant = "linkedin_apply_assistant.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/MohammedGhazal09/linkedin-apply-assistant#readme"
+Repository = "https://github.com/MohammedGhazal09/linkedin-apply-assistant"
+Issues = "https://github.com/MohammedGhazal09/linkedin-apply-assistant/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-p no:cacheprovider"
+markers = [
+  "live: opt-in tests that touch live services, real browser profiles, or network targets",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint.per-file-ignores]
+"tests/test_cli_contract.py" = ["E402"]
+"tests/test_runtime_boundaries.py" = ["E402"]
+"tests/test_runtime_decoupling.py" = ["E402"]

package/src/linkedin_apply_assistant/__init__.py

@@ -0,0 +1,8 @@
+"""Package identity for the standalone LinkedIn application assistant."""
+
+__version__ = "0.1.1"
+
+APP_DISPLAY_NAME = "LinkedIn-apply-assistant"
+APP_PACKAGE_NAME = "linkedin-apply-assistant"
+APP_IMPORT_NAME = "linkedin_apply_assistant"
+APP_COMMAND_NAME = "linkedin-apply-assistant"

package/src/linkedin_apply_assistant/apply_reports.py

@@ -0,0 +1,229 @@
+"""Package-local report writers for standalone runtime paths."""
+
+from __future__ import annotations
+
+from datetime import datetime
+import json
+from pathlib import Path
+import re
+from typing import Any
+from uuid import uuid4
+
+from .contracts import ReportArtifact
+from .paths import RuntimePaths
+from .redaction import sanitize_markdown_value, sanitize_report_payload
+
+
+def _timestamp() -> str:
+    return datetime.now().strftime("%Y-%m-%d_%H-%M-%S_%f")
+
+
+def _safe_filename_prefix(filename_prefix: str) -> str:
+    safe = re.sub(r"[^A-Za-z0-9_.-]+", "-", str(filename_prefix or "")).strip(".-")
+    return safe or "report"
+
+
+def _report_filename(filename_prefix: str, extension: str, *, timestamp: str | None = None) -> str:
+    report_timestamp = timestamp or _timestamp()
+    return (
+        f"{_safe_filename_prefix(filename_prefix)}_{report_timestamp}_{uuid4().hex[:8]}.{extension}"
+    )
+
+
+def _esc(value: Any) -> str:
+    return sanitize_markdown_value(value)
+
+
+def _event_context_label(event: dict[str, Any]) -> str:
+    job = event.get("job")
+    if not isinstance(job, dict):
+        job = {}
+    company = event.get("company") or job.get("company") or ""
+    role = event.get("role") or event.get("title") or job.get("role") or job.get("title") or ""
+    return f"{_esc(company)} {_esc(role)}".strip()
+
+
+def resolve_reports_dir(
+    paths: RuntimePaths | None = None,
+    reports_dir: str | Path | None = None,
+) -> Path:
+    """Resolve the report directory from explicit input or runtime paths."""
+
+    if reports_dir is not None:
+        return Path(reports_dir).expanduser()
+    if paths is not None:
+        return paths.reports_dir
+    raise ValueError("reports_dir or paths is required")
+
+
+def write_json_report(
+    report: dict[str, Any],
+    *,
+    paths: RuntimePaths | None = None,
+    reports_dir: str | Path | None = None,
+    filename_prefix: str = "report",
+) -> Path:
+    """Write a JSON report under an explicit standalone report directory."""
+
+    target_dir = resolve_reports_dir(paths=paths, reports_dir=reports_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    target = target_dir / _report_filename(filename_prefix, "json")
+    sanitized = sanitize_report_payload(report)
+    target.write_text(
+        json.dumps(sanitized, indent=2, ensure_ascii=False, default=str),
+        encoding="utf-8",
+    )
+    return target
+
+
+def write_markdown_report(
+    report: dict[str, Any],
+    *,
+    paths: RuntimePaths | None = None,
+    reports_dir: str | Path | None = None,
+    filename_prefix: str = "report",
+) -> Path:
+    """Write a compact Markdown report under an explicit standalone directory."""
+
+    target_dir = resolve_reports_dir(paths=paths, reports_dir=reports_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    report_timestamp = _timestamp()
+    target = target_dir / _report_filename(filename_prefix, "md", timestamp=report_timestamp)
+    sanitized = sanitize_report_payload(report)
+    summary = sanitized.get("summary", {}) if isinstance(sanitized, dict) else {}
+    events = sanitized.get("events", []) if isinstance(sanitized, dict) else []
+    lines = [
+        f"# LinkedIn-apply-assistant Report - {report_timestamp}",
+        "",
+    ]
+    if isinstance(summary, dict):
+        lines.append("## Summary")
+        lines.append("")
+        for key in sorted(summary):
+            lines.append(f"- **{_esc(key)}:** {_esc(summary[key])}")
+        lines.append("")
+    if isinstance(events, list):
+        lines.append("## Events")
+        lines.append("")
+        for event in events:
+            if isinstance(event, dict):
+                label = event.get("type", "event")
+                context_label = _event_context_label(event)
+                details = []
+                for key in (
+                    "status",
+                    "surface",
+                    "ats",
+                    "blocked_reason",
+                    "filled_count",
+                    "required_empty_count",
+                    "unknown_count",
+                    "domain",
+                ):
+                    value = event.get(key)
+                    if value not in (None, "", [], {}):
+                        details.append(f"{_esc(key)}={_esc(value)}")
+                suffix = f" - {'; '.join(details)}" if details else ""
+                lines.append(f"- **{_esc(label)}** {context_label}{suffix}".rstrip())
+        lines.append("")
+    target.write_text("\n".join(lines), encoding="utf-8")
+    return target
+
+
+def write_dry_run_report(jobs: list[dict[str, Any]], report_path: str | Path) -> Path:
+    """Write a dry-run JSON report to an explicit file path."""
+
+    target = Path(report_path).expanduser()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    passed = [job for job in jobs if job.get("pass")]
+    payload = {
+        "timestamp": _timestamp(),
+        "total": len(jobs),
+        "passed": len(passed),
+        "results": jobs,
+    }
+    safe_payload = sanitize_report_payload(payload)
+    target.write_text(json.dumps(safe_payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    return target
+
+
+def write_assistive_session_report(
+    report: dict[str, Any],
+    profile: dict[str, Any] | None = None,
+    *,
+    paths: RuntimePaths | None = None,
+    reports_dir: str | Path | None = None,
+) -> tuple[Path, Path]:
+    """Write JSON and Markdown reports for a local assistive session."""
+
+    prefix = "assistive-session"
+    payload = dict(report)
+    _ = profile
+    json_path = write_json_report(
+        payload,
+        paths=paths,
+        reports_dir=reports_dir,
+        filename_prefix=prefix,
+    )
+    md_path = write_markdown_report(
+        payload,
+        paths=paths,
+        reports_dir=reports_dir,
+        filename_prefix=prefix,
+    )
+    return json_path, md_path
+
+
+def write_search_report(
+    report: dict[str, Any],
+    *,
+    paths: RuntimePaths | None = None,
+    reports_dir: str | Path | None = None,
+) -> tuple[Path, Path]:
+    """Write JSON and Markdown reports for a search workflow."""
+
+    json_path = write_json_report(
+        report,
+        paths=paths,
+        reports_dir=reports_dir,
+        filename_prefix="search",
+    )
+    md_path = write_markdown_report(
+        report,
+        paths=paths,
+        reports_dir=reports_dir,
+        filename_prefix="search",
+    )
+    return json_path, md_path
+
+
+class RuntimeReportSink:
+    """ReportSink implementation backed by explicit runtime paths."""
+
+    def __init__(
+        self,
+        *,
+        paths: RuntimePaths | None = None,
+        reports_dir: str | Path | None = None,
+    ) -> None:
+        self.paths = paths
+        self.reports_dir = reports_dir
+
+    def write(self, command: str, report: dict[str, Any]) -> list[ReportArtifact]:
+        prefix = "assistive-session" if command == "assist" else command
+        json_path = write_json_report(
+            report,
+            paths=self.paths,
+            reports_dir=self.reports_dir,
+            filename_prefix=prefix,
+        )
+        md_path = write_markdown_report(
+            report,
+            paths=self.paths,
+            reports_dir=self.reports_dir,
+            filename_prefix=prefix,
+        )
+        return [
+            ReportArtifact(kind="json", path=json_path),
+            ReportArtifact(kind="markdown", path=md_path),
+        ]