feat(cli): add secure clamshell control foundation

.coderabbit.yaml

@@ -0,0 +1,111 @@
+# yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json
+language: "en-GB"
+early_access: false
+
+reviews:
+  profile: "assertive"
+  request_changes_workflow: true
+  high_level_summary: true
+  high_level_summary_in_walkthrough: true
+  high_level_summary_instructions: >-
+    Summarise user-visible behaviour, security boundaries, and verification in
+    concise British English. Use ASD-STE100 Simplified Technical English for
+    documentation. Keep required technical terms, product names, commands,
+    identifiers, quoted interface text, and standard names. Omit release-note
+    filler.
+  review_status: true
+  review_details: false
+  commit_status: true
+  fail_commit_status: false
+  collapse_walkthrough: true
+  changed_files_summary: true
+  sequence_diagrams: false
+  estimate_code_review_effort: false
+  assess_linked_issues: true
+  related_issues: false
+  related_prs: false
+  suggested_labels: false
+  auto_apply_labels: false
+  suggested_reviewers: false
+  in_progress_fortune: false
+  poem: false
+  enable_prompt_for_ai_agents: false
+  abort_on_close: true
+
+  auto_review:
+    enabled: true
+    auto_incremental_review: false
+    drafts: false
+
+  finishing_touches:
+    docstrings:
+      enabled: false
+
+  pre_merge_checks:
+    docstrings:
+      mode: "off"
+    title:
+      mode: "off"
+    description:
+      mode: "warning"
+    issue_assessment:
+      mode: "warning"
+
+  path_instructions:
+    - path: "**/*"
+      instructions: |
+        Report only findings with a concrete correctness, security, or
+        maintainability consequence. State the consequence and the smallest
+        suitable remedy. Do not request cosmetic churn, redundant comments,
+        or documentation for self-explanatory implementation details. Verify
+        each finding against the current code and repository conventions.
+    - path: "**/*.swift"
+      instructions: |
+        Follow the Google Swift Style Guide and the repository SwiftLint
+        policy. Prefer idiomatic Swift 6, narrow access control, Sendable-safe
+        concurrency, typed errors, and explicit failure handling. Treat one
+        primary responsibility per file as a design goal, not a rigid
+        one-declaration rule.
+    - path: "Sources/ClamshellCore/Privilege/**/*.swift"
+      instructions: |
+        Treat helper actions, sudoers generation, filesystem replacement,
+        ownership, permissions, username handling, and process construction as
+        security boundaries. Check exact allow-lists and failure consistency.
+    - path: "Sources/ClamshellHelper/**/*.swift"
+      instructions: |
+        Treat every accepted argument and privileged command as part of the
+        root boundary. Reject broader command shapes and require observable
+        verification of requested state changes.
+    - path: "Tests/**/*.swift"
+      instructions: |
+        Review observable behaviour, failure paths, and privilege constraints.
+        Tests must not mutate live power settings or privileged system files.
+        Do not request assertions about private implementation or call order
+        unless order is part of the contract.
+    - path: ".github/workflows/**"
+      instructions: |
+        Check immutable action pinning, least-privilege permissions, untrusted
+        pull-request code execution, concurrency, timeouts, and fail-closed
+        status handling. Request comments only for non-obvious security
+        constraints or necessary tool suppressions.
+    - path: "scripts/**"
+      instructions: |
+        Check quoting, exit-status preservation, temporary-file cleanup, and
+        fail-closed behaviour. Prefer portable shell accepted by ShellCheck.
+    - path: "**/*.md"
+      instructions: |
+        Check technical accuracy against current behaviour. Require ASD-STE100
+        Simplified Technical English and British English spelling. Permit
+        required technical terms, product names, commands, identifiers, quoted
+        interface text, and standard names. Reject stale paths, unsupported
+        claims, and internal AI process metadata.
+
+  tools:
+    swiftlint:
+      enabled: true
+      config_file: ".swiftlint.yml"
+    shellcheck:
+      enabled: true
+
+chat:
+  auto_reply: true

.editorconfig

@@ -0,0 +1,19 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.swift]
+indent_style = space
+indent_size = 2
+max_line_length = 100
+
+[{*.json,*.yml,*.yaml}]
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+*.icns binary
+*.png binary
+*.dmg binary

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @LMLiam

.github/CONTRIBUTING.md

@@ -0,0 +1,103 @@
+# Contributing
+
+## Prerequisites
+
+You need macOS, Xcode 26.6 or later, and Swift 6.3 or later. You also need
+SwiftLint 0.65.0 and [actionlint](https://github.com/rhysd/actionlint).
+Install the development tools with:
+
+```bash
+brew install actionlint swiftlint
+```
+
+The future companion app also requires
+[XcodeGen](https://github.com/yonaskolb/XcodeGen).
+
+## Setup
+
+Fork the repository, clone your fork, and create a branch from `main`. Resolve
+the package dependencies once after cloning:
+
+```bash
+swift package resolve
+```
+
+Do not run tests against live privileged paths. Tests must use fake process and
+filesystem boundaries; they must never change `pmset`, invoke `sudo`, or write
+to `/Library/PrivilegedHelperTools` or `/etc/sudoers.d`.
+
+## Checks
+
+Run the complete local gate before each pull request:
+
+```bash
+scripts/check.sh
+```
+
+The script checks formatting, SwiftLint, tests, debug and release builds, and
+GitHub Actions workflows. When native app targets exist, it also generates and
+builds the Xcode project without code signing.
+
+## Swift style
+
+Follow the [Google Swift Style Guide](https://google.github.io/swift/).
+`swift-format` owns formatting; SwiftLint owns semantic and maintainability
+rules. Prefer self-describing names. Add comments only for contracts,
+constraints, or decisions that the code does not make clear.
+
+Keep one primary responsibility per file. A private helper may remain beside
+its sole consumer. Do not create generic `Utils`, `Common`, or `Models`
+directories.
+
+Fix lint findings in code where practical. A SwiftLint suppression must have a
+narrow scope and an adjacent explanation of why the rule does not apply.
+
+## Documentation style
+
+Use ASD-STE100 Simplified Technical English for all documentation. Use British
+English spelling. Use short sentences and active voice. Give one instruction
+in each sentence. Use one term for each item or action.
+
+You can use an unapproved term when technical accuracy requires it. Examples
+include product names, commands, code identifiers, API names, quoted interface
+text, and standard names. Do not replace a precise technical term with an
+ambiguous word.
+
+## Commits
+
+Every commit and pull-request title must use:
+
+```text
+verb(area): description
+```
+
+Examples include `feat(status): report battery state` and
+`fix(setup): preserve an existing sudoers policy`. The accepted verbs are
+`feat`, `fix`, `docs`, `test`, `build`, `ci`, `refactor`, `perf`, `style`,
+`chore`, and `revert`.
+
+Dependency updates use `build(deps): ...` so they remain within the accepted
+commit vocabulary and are hidden from the public changelog.
+
+## Tests
+
+Test observable behaviour through public or internal boundaries. Cover failure
+paths and privilege constraints. Avoid assertions about private implementation
+details, mock call order unless order is part of the contract, and live system
+mutation.
+
+## Pull requests
+
+Keep each pull request focused and link the issue it addresses. Describe any
+change to command output, exit status, system paths, permissions, sudoers
+policy, or the helper allow-list. Include the commands you ran and update user
+documentation when behaviour changes.
+
+Maintainer approval and all required checks are needed before merge. The
+repository uses squash merging, so the pull-request title becomes the release
+commit subject.
+
+## Security
+
+Do not report vulnerabilities in a public issue. Follow the private reporting
+instructions in [SECURITY.md](SECURITY.md).

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/LMLiam/clamshellctl/security/advisories/new
+    about: Send vulnerability details privately to the maintainer.
+  - name: Support and usage questions
+    url: https://github.com/LMLiam/clamshellctl/issues/new?template=question.yml
+    about: Ask about macOS, Homebrew, or clamshellctl usage.

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,50 @@
+name: Support question
+description: Ask about macOS, Homebrew, or clamshellctl usage.
+title: "question(area): "
+labels:
+  - question
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Do not include passwords, tokens, private keys, complete environment
+        dumps, or unrelated personal information.
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: Explain what you are trying to do and where you are stuck.
+    validations:
+      required: true
+  - type: input
+    id: macos-version
+    attributes:
+      label: macOS version
+      placeholder: "26.6"
+    validations:
+      required: true
+  - type: dropdown
+    id: installation
+    attributes:
+      label: Installation method
+      options:
+        - Homebrew
+        - Companion-app DMG
+        - Source checkout
+        - Not installed
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Safe diagnostic output
+      description: Include concise command output when it helps explain the question.
+    validations:
+      required: false
+  - type: checkboxes
+    id: safety
+    attributes:
+      label: Safety check
+      options:
+        - label: I removed passwords, tokens, private keys, and unrelated personal data.
+          required: true

.github/SECURITY.md

@@ -0,0 +1,28 @@
+# Security policy
+
+## Supported versions
+
+Only the latest published release receives security fixes. The project has not
+published its first release yet.
+
+## Report a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/LMLiam/clamshellctl/security/advisories/new).
+Do not open a public issue for a suspected vulnerability.
+
+Include the affected version, macOS version, impact, reproduction steps, and a
+minimal proof when safe. Do not include live credentials, secrets, personal
+data, or destructive commands. We will acknowledge a report within seven days
+and keep you informed while we validate and fix it.
+
+## Security-sensitive surfaces
+
+Changes to the root-owned helper, sudoers policy, installation paths, ownership
+or permissions, process execution, and unsigned app distribution require extra
+review. The helper must continue to accept only the exact `enable` and
+`disable` actions. The sudoers policy must not grant password-free access to
+the public CLI, `pmset`, a shell, or a user-writable executable.
+
+The planned companion app and DMG will use ad-hoc signing without Apple
+notarisation. Release documentation must state that boundary and provide the
+specific Gatekeeper approval steps without implying Apple review.

.github/SUPPORT.md

@@ -0,0 +1,14 @@
+# Support
+
+- Report reproducible defects with the [bug form](https://github.com/LMLiam/clamshellctl/issues/new?template=bug.yml).
+- Propose a change with the [feature form](https://github.com/LMLiam/clamshellctl/issues/new?template=feature.yml).
+- Report vulnerabilities through [private vulnerability reporting](https://github.com/LMLiam/clamshellctl/security/advisories/new).
+- Ask macOS, Homebrew, or usage questions with the [support form](https://github.com/LMLiam/clamshellctl/issues/new?template=question.yml).
+
+This is a community project. Opening an issue does not guarantee individual
+support or a response time.
+
+Safe diagnostics include `clamshellctl --version` and `clamshellctl status`.
+Review output before posting it. Do not publish sudoers contents when they
+contain unexpected local changes; use private vulnerability reporting if those
+changes may expose a security problem.

.github/dependabot.yml

@@ -0,0 +1,27 @@
+version: 2
+updates:
+  - package-ecosystem: swift
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    open-pull-requests-limit: 5
+    groups:
+      swift-development:
+        patterns:
+          - "*"
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+      time: "06:00"
+      timezone: Europe/London
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns:
+          - "*"