Project 1: Pocket Runtime Cartographer

Build a capability-aware pocketctl doctor that proves what Android, Termux, packages, add-ons, permissions, and hardware are actually available before later tools act.

Quick Reference

Attribute Value
Difficulty Level 1 - Beginner
Time Estimate 6-10 hours
Language POSIX shell for discovery; Python for validation and rendering (alternatives: Bash, Go, Rust)
Prerequisites Basic shell use, JSON, process environment, exit statuses
Key Topics Android sandbox, HOME/PREFIX, installation tracks, capability negotiation, CLI schemas, redaction

1. Learning Objectives

By completing this project, you will:

  1. Explain why Termux is an Android-hosted userspace rather than a Linux virtual machine.
  2. Separate facts supplied by Android, the Termux app, the package tree, an add-on, a runtime permission, and device hardware.
  3. Design bounded, side-effect-free probes that cannot hang the doctor indefinitely.
  4. Produce equivalent human and versioned JSON views over one typed result model.
  5. Distinguish READY, DEGRADED, and BLOCKED states with stable recovery-oriented error codes.
  6. Test device-dependent discovery with fake command adapters before using a physical phone.
  7. Redact identifiers and secrets while preserving enough evidence to diagnose an installation.

2. Theoretical Foundation

2.1 Core Concepts

Termux preserves many Unix process concepts—arguments, environment variables, file descriptors, pipes, signals, sockets, and child processes—but runs them inside an Android application sandbox. Android owns the kernel, Bionic C library, application UID, private data directory, permissions, SELinux policy, package signatures, and process lifecycle. Termux supplies the terminal application, bootstrap, package repository, HOME, PREFIX, shell sessions, and optional Android bridges.

That split explains why a command can behave like a normal Unix program yet fail when it assumes /usr/bin, glibc, systemd, unrestricted /proc, root-owned configuration, or an immortal daemon. The doctor must not answer the vague question “is this Linux?” It must answer the operational questions later projects rely on: which runtime is active, where are trusted files installed, which ABI is selected, which integration track is present, and which capabilities are usable now?

 Android-owned facts                         Termux-owned facts
 +----------------------------------+         +--------------------------------+
 | app UID, sandbox, permissions    |         | HOME, PREFIX, package database |
 | Android/API version, ABI/kernel  | <-----> | shell, tools, child processes  |
 | process lifecycle, signatures   |         | add-on clients and adapters    |
 +----------------------------------+         +--------------------------------+
                    \                         /
                     \                       /
                      +---------------------+
                      | doctor observations |
                      | typed + timestamped |
                      +---------------------+

Key distinction: an observation is a fact returned by a probe; a capability state is a policy conclusion computed from several observations. Keeping these separate prevents a misleading rule such as “command exists, therefore capability works.”

HOME, PREFIX, environment, and launch surfaces

On the classic com.termux installation in the primary Android user, HOME normally resolves beneath /data/data/com.termux/files/home and PREFIX beneath /data/data/com.termux/files/usr. These paths are part of a relocated Termux userspace. They are not portable constants for forks, secondary-user installations, or future product tracks, so a tool should consume validated environment values rather than splice strings into those examples.

Interactive sessions commonly load shell profiles that add language managers, aliases, custom PATH entries, agent sockets, and locale settings. A Widget task, Tasker request, boot hook, service, or restricted SSH command may not receive that same environment. The doctor should therefore record both the stable runtime foundation and the current launch context. It should not serialize and replay the entire interactive environment: doing so can copy secrets, stale sockets, terminal-only flags, or developer-specific paths.

An external launch needs a small documented manifest:

  • Expected HOME and PREFIX relationship.
  • Minimal PATH derived from PREFIX.
  • Locale and temporary-directory policy.
  • Whether stdin/stdout are attached to a TTY.
  • Entry-surface name and current working directory.
  • Required schema and tool version.

Installation tracks and signing lineage

This project uses the classic F-Droid/GitHub track as its reference model. On that track, Termux and companion applications such as Termux:API, Widget, Boot, and Tasker share an application identity. The official Termux installation guidance states that the main app and plug-ins must be signed with the same key and therefore installed from the same source family. Do not mix an F-Droid main app with a GitHub add-on, or the reverse. A source change requires a deliberate backup, removal of the incompatible family, and reinstall from one lineage.

The Google Play track is a separate product line for newer Android versions. Its current integration surface differs: Widget and Boot behavior is merged into the main app, only a subset of API tools is built in, and Tasker is not currently part of that track. The doctor should report the track as a first-class dimension and say NOT_APPLICABLE where a classic add-on check does not match the Play architecture. It must never “repair” a Play installation by recommending a classic plug-in APK.

Signing compatibility cannot be proven by testing only for a package name. A layered check can report:

  1. Expected main application track.
  2. Client command or built-in feature presence.
  3. Companion APK presence when that track requires one.
  4. Compatible interaction result.
  5. Runtime permission state.
  6. Hardware/provider availability.

Capability negotiation

A capability is not Boolean. Consider location telemetry. The command wrapper may be absent; the add-on may be absent; signatures may prevent communication; permission may be denied; the provider may be disabled; hardware may be unsupported; the request may time out; or a stale value may be returned. Each condition has different remediation and retry behavior.

Use a state model that preserves both lifecycle and recovery meaning:

State Meaning Typical Recovery
READY Required layers responded with valid data None
DEGRADED Optional feature unavailable or partial result remains useful Continue with reduced function
BLOCKED Required prerequisite is unsatisfied User or setup action required
PERMISSION_REQUIRED Installed capability lacks user-granted authority Grant only the required permission
UNSUPPORTED Track, API level, provider, or hardware cannot supply it Disable profile or use another device
TRANSIENT_FAILURE Capability exists but failed temporarily Bounded retry
MALFORMED_RESPONSE Adapter returned data outside its contract Preserve bounded evidence and investigate

Do not let policy hide raw evidence. A result should retain which probe ran, its safe observation, elapsed time, timestamp, and adapter version. The renderer can then explain why a capability became degraded without rerunning probes.

CLI contracts and observability

The doctor is the first public PocketOps interface. Standard output carries the selected report, standard error carries diagnostics about producing it, and the exit status gives automation a coarse outcome. JSON mode must emit exactly one complete document. Warnings, progress, and debug traces must never corrupt that document.

A stable schema should include:

  • Schema identifier and tool version.
  • Report timestamp and correlation ID.
  • Track, Android, ABI, HOME, and PREFIX summaries.
  • One object per observation and capability.
  • Overall state derived by documented policy.
  • Recovery actions using stable codes.
  • Redaction metadata stating what was intentionally omitted.

Human output is a view over that schema, not an independent implementation. If JSON says PERMISSION_REQUIRED while the table says READY, the architecture has already failed.

Privacy and safe evidence

A support report is tempting to make exhaustive, but exhaustive device reports often become fingerprinting artifacts. Default output should exclude precise location, clipboard contents, message data, network credentials, package signing secrets, SSH material, persistent hardware identifiers, full Wi-Fi identifiers, and environment values likely to contain tokens. Prefer coarse or transformed evidence: Android major/API version, ABI, available disk space, redacted path classes, package presence, and keyed or truncated identifiers only where correlation is justified.

Verbose diagnostics should be explicit, short-lived, and still apply a denylist. Logging raw environment dumps is not an acceptable shortcut.

2.2 Why This Matters

Every later project can damage state, request Android authority, expose a listener, or make an operational promise. A truthful preflight turns hidden assumptions into explicit capability decisions before those effects occur. The same pattern is used by installers, device-enrollment systems, deployment agents, and support tools.

2.3 Historical Context / Background

Termux preserved familiar Unix composition while Android progressively tightened executable paths, scoped storage, background work, app signing, and cross-application access. Its relocated PREFIX, patched packages, plug-ins, and separate current Play track are responses to that platform history. The doctor captures the resulting runtime facts instead of relying on instructions written for an older Android or Termux release.

2.4 Common Misconceptions

  • “Termux is Ubuntu on Android.” It is an Android application with its own relocated userspace and packages.
  • “If a client command exists, the capability is ready.” An add-on, signing compatibility, permission, provider, and hardware may still be missing.
  • “The exact /data/data/com.termux path is universal.” It is the classic primary-user default, not a portable API.
  • “Exit 0/1 is enough.” Automation needs to choose between user action, unsupported capability, retry, and internal fault.
  • “More diagnostics are always better.” Unbounded evidence can leak secrets or uniquely identify a device.

3. Project Specification

3.1 What You Will Build

Build a pocketctl doctor operation with two render modes and a reusable capability library. The first release inspects:

  • Termux distribution track and release hints.
  • Android version/API level and CPU/package architecture.
  • HOME, PREFIX, PATH foundation, shell, TTY state, and entry surface.
  • Required package commands and optional integration clients.
  • Private-storage headroom and shared-storage readiness as observations only.
  • Classic-track add-on layers without mixing source lineages.
  • Service-supervisor presence as optional readiness.
  • Network interface hints without claiming Internet reachability.

3.2 Functional Requirements

  1. Typed observations: Every probe returns source, state, safe detail, elapsed time, and recovery code.
  2. Derived policy: Required and optional capability rules are evaluated after probing.
  3. Human rendering: A compact table explains status and ordered actions.
  4. JSON rendering: A versioned schema represents the same model without extra stdout bytes.
  5. Bounded execution: Every external process has a deadline, output limit, and cancellation path.
  6. Track-aware checks: Classic and Play installations are classified without cross-track repair advice.
  7. Redaction: Default reports omit secrets and persistent device identifiers.
  8. Deterministic fixtures: Stored adapter transcripts cover absent, denied, unsupported, malformed, timeout, and partial states.

3.3 Non-Functional Requirements

  • Performance: Complete local-only probes in under three seconds on the reference phone; mark slower optional probes separately.
  • Reliability: A failed probe cannot prevent unrelated observations from rendering.
  • Compatibility: Unknown schema fields are tolerated by readers; breaking changes require a new schema identifier.
  • Usability: Every non-ready required state names exactly one next action.
  • Security: Probes are read-only and do not silently request permissions or alter system configuration.

3.4 Example Usage / Output

{
  "schema": "pocketops.doctor.v1",
  "status": "degraded",
  "track": "classic-fdroid",
  "runtime": {
    "abi": "aarch64",
    "home_class": "termux_private",
    "prefix_class": "termux_private"
  },
  "capabilities": {
    "termux_api": {
      "state": "permission_required",
      "recovery_code": "GRANT_SELECTED_API_PERMISSION"
    }
  },
  "redactions": ["persistent_device_ids", "network_names", "environment_secrets"]
}

This is a schema shape, not a complete implementation.

3.5 Real World Outcome

Install the reference classic track from one official source family, open Termux once so the bootstrap exists, and run the doctor from a normal terminal session. The screen shows a title and schema, then aligned rows for track, Android/API, ABI, HOME, PREFIX, private storage, Termux:API, Widget/Boot expectations, and services. Each row includes a textual state so color is optional. The final block gives the overall state, action count, and numbered recovery steps.

Next, select JSON mode and pipe it to a JSON validator. The output is one parseable document with the same states. Hide one optional command through a fake adapter, revoke one selected API permission, feed a malformed add-on response, and delay a probe beyond its deadline. Each scenario produces a distinct code while unrelated facts remain visible.

Finally, run the same entry point from one external surface available on the chosen track. Compare the redacted runtime manifest. PATH and TTY may differ, but HOME/PREFIX classification, schema, and capability policy remain equivalent.

$ pocketctl doctor
PocketOps Runtime Doctor  schema=pocketops.doctor.v1
Track       classic-fdroid        READY
Android     13 / API 33           READY
ABI         aarch64               READY
HOME        .../files/home        READY
PREFIX      .../files/usr         READY
Storage     private 18.4 GiB free READY
Termux:API  client + add-on       PERMISSION_REQUIRED
Boot        add-on detected       READY
Services    runsvdir not running  DEGRADED

Result: DEGRADED (2 actions)
1. Grant the selected Termux:API permission.
2. Start the service supervisor before enabling services.
Exit status: 20

The finished artifact is not merely a pretty report. It is a tested capability contract reused by Projects 2-12.

3.6 Edge Cases

  • HOME or PREFIX absent, relative, unexpected, or internally inconsistent.
  • Command found through an interactive-only PATH entry.
  • Command emits binary, enormous, malformed, or locale-dependent output.
  • Probe prompts for input despite being classified as read-only.
  • Main app and add-on exist but cannot communicate because signing lineages differ.
  • Play track exposes a built-in capability that classic expects from an add-on.
  • Disk is nearly full while the report itself needs temporary space.
  • Android version or architecture cannot be parsed into a known enum.
  • TTY absent and renderer attempts animation or color.

4. Solution Architecture

4.1 High-Level Design

 shell / Widget / test fixture
             |
             v
 +------------------------+
 | request + output mode  |
 +-----------+------------+
             |
             v
 +------------------------+      +-----------------------+
 | probe coordinator      |----->| bounded adapters      |
 | deadline + concurrency |      | env/pkg/android/fs    |
 +-----------+------------+      +-----------+-----------+
             |                               |
             +--------- observations <------+
             |
             v
 +------------------------+
 | capability policy      |
 | required/optional      |
 +-----------+------------+
             |
       typed report
      +------+------+
      |             |
 human renderer  JSON renderer

4.2 Key Components

Component Responsibility Key Decision
Request parser Select profile, output mode, and safe diagnostic level Parsing performs no probes
Probe registry Declares probe identity, cost, deadline, and sensitivity Metadata is inspectable and testable
Process adapter Runs bounded external commands Capture stdout/stderr separately with size limits
Environment adapter Reads approved environment fields Allowlist rather than full dump
Track detector Classifies classic F-Droid/GitHub, Play, or unknown Unknown never guesses add-on instructions
Capability policy Combines observations into operational states Pure function over observations
Redactor Removes or transforms sensitive evidence Redact before logs and rendering
Renderers Produce human or JSON contracts Both consume the same report object

4.3 Data Structures

Observation:
    probe_id
    source_layer = ANDROID | TERMUX_APP | PACKAGE | ADDON | PERMISSION | HARDWARE
    state = OBSERVED | ABSENT | DENIED | UNSUPPORTED | TIMEOUT | MALFORMED
    safe_detail
    evidence_digest
    elapsed_ms
    observed_at

CapabilityResult:
    capability_id
    state = READY | DEGRADED | BLOCKED
    contributing_probe_ids[]
    recovery_code?
    retryable

DoctorReport:
    schema
    correlation_id
    track
    observations[]
    capabilities[]
    overall_state
    redaction_summary[]

4.4 Algorithm Overview

Doctor evaluation

  1. Validate request and choose a known profile.
  2. Select probes from the registry.
  3. Run safe independent probes within per-probe and total deadlines.
  4. Convert adapter outputs into typed observations.
  5. Redact safe detail at the boundary.
  6. Evaluate capability rules over completed observations.
  7. Sort recovery actions by required impact and user effort.
  8. Render one contract and map overall state to a documented exit status.

Complexity analysis

  • Time: O(P) logical probe processing, with wall time bounded by total deadline rather than the sum of all independent probes.
  • Space: O(P + B), where P is probe count and B is the global bounded evidence budget.

5. Implementation Guide

5.1 Development Environment Setup

Use a supported Termux installation and record its source before adding integrations. On the classic track, install every plug-in from that exact same F-Droid or GitHub signing family. Back up private state before changing sources. On Play, use the merged/built-in capability surface and do not install classic add-ons as a workaround.

Suggested learning tools include a shell, Python, Git, a JSON validator, the Termux package database, and a test runner. The first milestone needs no dangerous Android permission.

5.2 Project Structure

pocket-runtime-cartographer/
├── docs/
│   ├── capability-model.md
│   └── exit-statuses.md
├── schemas/
│   └── pocketops.doctor.v1.schema.json
├── src/
│   ├── request-and-policy/
│   ├── adapters/
│   ├── redaction/
│   └── renderers/
├── fixtures/
│   ├── classic-ready/
│   ├── play-partial/
│   └── failures/
├── tests/
└── README.md

5.3 The Core Question You’re Answering

“What environment does this command truly run in, and how can every later tool prove its assumptions before acting?”

If you cannot attribute a fact to a specific layer, the doctor is still guessing. Make a source-layer diagram before implementing the parser.

5.4 Concepts You Must Understand First

  1. Application sandbox: Which access comes from the app UID rather than a shell user account?
  2. Relocated userspace: Why do HOME and PREFIX replace desktop filesystem assumptions?
  3. Environment inheritance: Which launch surfaces do not source interactive profiles?
  4. Capability negotiation: Why do installed, callable, permitted, and supported differ?
  5. Output contracts: Why must JSON stdout remain free of diagnostics?
  6. Signing lineage: Why must classic Termux and plug-ins come from one source family?

5.5 Questions to Guide Your Design

  • Which probes are completely read-only?
  • What is the maximum acceptable runtime and output size for each probe?
  • Can the policy evaluator run using only stored fixtures?
  • Which facts are safe in a bug report?
  • How will unknown tracks and future fields degrade?
  • Which exit codes are stable public interface rather than internal implementation detail?

5.6 Thinking Exercise

Draw a matrix for the location capability with columns for client command, add-on/built-in bridge, signing compatibility, permission, provider, and hardware. Fill at least eight failure combinations. For each, decide:

  • observation state;
  • capability state;
  • whether the result is retryable;
  • whether a user action exists;
  • which evidence is safe to render.

5.7 The Interview Questions They’ll Ask

  1. “How is Termux different from a Linux VM or container?”
  2. “Why can PATH differ between terminal, Widget, Tasker, Boot, and service launches?”
  3. “How would you version a CLI JSON contract?”
  4. “What is capability negotiation?”
  5. “How do Android package signatures affect classic Termux add-ons?”
  6. “How would you test a device doctor without owning every phone?”

5.8 Hints in Layers

Hint 1: Inventory before policy

Return observations without READY/BLOCKED conclusions. Write the policy as a separate pure transformation.

Hint 2: Bound every process

The process adapter should require a deadline and output budget. A probe definition without them is invalid.

Hint 3: Make track explicit

Do not infer “classic” merely because an add-on is missing. Support UNKNOWN and provide a source-inspection action.

Hint 4: Contract-test both renderers

Given one stored DoctorReport, assert the human table and JSON schema independently. Do not rerun probes in renderer tests.

5.9 Books That Will Help

Topic Book Chapter
Shell environment and expansion “The Linux Command Line,” William Shotts Ch. 11
Processes and credentials “The Linux Programming Interface,” Michael Kerrisk Ch. 6 and 28
Program boundaries “Clean Architecture,” Robert C. Martin Ch. 20-22
Defensive interfaces “The Pragmatic Programmer,” Hunt and Thomas Orthogonality and contracts sections

5.10 Implementation Phases

Phase 1: Observation Core (2-3 hours)

Goals

  • Define schemas, status vocabulary, and redaction rules.
  • Implement pure environment and fixture adapters.

Tasks

  1. Write the source-layer and capability-state tables.
  2. Define probe metadata and result types.
  3. Create fixtures for ready, absent, denied, timeout, and malformed results.
  4. Render a report entirely from fixtures.

Checkpoint: Human and JSON modes agree on one fixture report and JSON stdout parses cleanly.

Phase 2: Real Device Probes (2-4 hours)

Goals

  • Inspect runtime, package, storage, and track facts safely.
  • Enforce deadlines and evidence bounds.

Tasks

  1. Add one adapter at a time and document its source layer.
  2. Record classic/Play/unknown behavior without cross-track assumptions.
  3. Add per-probe timing and total deadline cancellation.
  4. Compare interactive and one external launch environment.

Checkpoint: A failed optional probe leaves required facts and one complete report intact.

Phase 3: Policy, Privacy, and Acceptance (2-3 hours)

Goals

  • Derive actionable readiness without leaking sensitive data.
  • Prove compatibility and failure behavior.

Tasks

  1. Add required/optional profiles and exit mappings.
  2. Test every redaction canary across stdout, stderr, and logs.
  3. Exercise same-signing-lineage guidance using fixtures, not by deliberately corrupting the primary phone.
  4. Save a redacted acceptance transcript.

Checkpoint: Six injected failures produce distinct stable states and no canary secret appears anywhere.

5.11 Key Implementation Decisions

Decision Options Recommendation Rationale
Probe scheduling Sequential; concurrent Small bounded concurrency Faster while keeping resource use and deadlines predictable
Raw evidence Discard; retain all; bounded digest/detail Bounded safe detail plus digest Supports diagnosis without collecting secrets
Track detection Boolean classic; enum Extensible enum with UNKNOWN Prevents wrong repair instructions
Human/JSON logic Separate pipelines; shared model Shared typed model Eliminates semantic drift
Exit statuses One generic error; stable classes Small documented class set Useful to automation without exposing internals

6. Testing Strategy

6.1 Test Categories

Category Purpose Examples
Unit Validate pure policy and redaction Observation combinations, path classification
Contract Protect schema and channel behavior JSON schema, exit mapping, no stderr in stdout
Adapter Translate bounded command outputs Missing command, timeout, huge output, malformed encoding
Integration Combine real Termux layers Package database, HOME/PREFIX, selected API probe
Cross-surface Detect environment drift Terminal versus Widget/other available surface
Privacy Prevent evidence leaks Canary tokens in environment and adapter output

6.2 Critical Test Cases

  1. Missing optional client: Overall state is degraded, not blocked.
  2. Missing required runtime path: Overall state is blocked with one precise action.
  3. Permission revoked: Client and add-on remain present; state becomes permission-required.
  4. Unsupported hardware: No permission prompt is suggested.
  5. Timed-out probe: Unrelated observations render; process completes within total deadline.
  6. Malformed JSON: Bounded evidence digest is retained; parser never crashes the report.
  7. Play partial surface: Built-in capabilities are not incorrectly labeled missing plug-ins.
  8. Lineage mismatch fixture: Result names compatibility without recommending mixed-source installation.
  9. Redaction canary: Secret-like values never appear in any output channel.
  10. TTY absent: Output has no animation or forced ANSI escapes.

6.3 Test Data

fixture classic-ready:
    track=classic-fdroid
    api_client=present
    api_addon=present
    permission=granted

fixture classic-denied:
    same installation facts
    permission=denied

fixture play-partial:
    track=play
    widget=built_in
    api_subset=built_in
    tasker=not_available

fixture hostile-output:
    stdout_size=over_limit
    includes=CANARY_SECRET
    encoding=malformed

7. Common Pitfalls & Debugging

7.1 Frequent Mistakes

Pitfall Symptom Solution
Treating command presence as readiness Add-on call still fails Probe client, bridge, permission, and hardware separately
Hard-coded /usr or /bin Bad interpreter or wrong command Derive validated paths from PREFIX
Full environment dump Tokens leak into report Use an allowlist and redaction canaries
Unbounded subprocess Doctor hangs forever Require deadline and output budget in probe metadata
Mixed track assumptions Play install receives classic add-on advice Make distribution track explicit
Renderer computes status Human and JSON disagree Evaluate policy before rendering

7.2 Debugging Strategies

  • Inspect the stored observation before inspecting the final policy conclusion.
  • Replay the exact adapter fixture outside the phone.
  • Compare redacted environment keys across launch surfaces.
  • Verify main app and classic add-ons came from the same official source lineage.
  • Use Android logs only after capturing stdout, stderr, exit status, correlation ID, and tool logs.
  • Disable verbose diagnostics after use; verbose bridge logs can expose private data and increase overhead.

7.3 Performance Traps

  • Launching dozens of external processes serially.
  • Running network reachability checks in a runtime doctor; network truth belongs in Project 5.
  • Capturing unbounded package inventories when only declared requirements matter.
  • Recomputing unchanged static facts on every subcommand instead of caching with a safe invalidation key.

8. Extensions & Challenges

8.1 Beginner Extensions

  • Add doctor explain <code> for offline recovery documentation.
  • Add a diff between two redacted reports.
  • Add a profile that checks only Project 2 prerequisites.

8.2 Intermediate Extensions

  • Sign exported support reports with a local ephemeral support key.
  • Add capability-cache invalidation when package or Android permission state changes.
  • Create a compatibility report for classic versus Play without claiming feature parity.

8.3 Advanced Extensions

  • Build a declarative probe registry with schema-validated plug-ins that cannot execute arbitrary shell text.
  • Produce an anonymized fleet compatibility summary using only coarse fields and explicit consent.
  • Model uncertainty when package/app identity cannot be inspected without ADB or privileged APIs.

9. Real-World Connections

9.1 Industry Applications

  • Device enrollment: Enterprise agents prove OS, architecture, storage, and permission prerequisites before provisioning.
  • Support bundles: Production tools produce redacted, versioned evidence instead of asking users for screenshots.
  • Feature flags by capability: Mobile and edge systems enable functions only when the current environment can support them.
  • Preflight checks: Installers and deployment tools stop before unsafe partial changes.
  • Termux app: The Android terminal and execution host this project describes.
  • termux-packages: Defines the relocated package runtime and execution constraints.
  • Termux:API: Demonstrates the multi-layer client/add-on/permission capability model.
  • clig.dev: Community guidance for predictable command-line interfaces.

9.3 Interview Relevance

This project demonstrates environment modeling, backward-compatible contracts, subprocess safety, privacy-by-default observability, feature detection, and testable adapter architecture. Those skills transfer directly to installers, CI agents, edge software, desktop support tools, and container preflight systems.

10. Resources

10.1 Essential Reading

10.2 Video Resources

  • Android platform talks on application sandboxing and permissions from the official Android Developers channel.
  • “The Missing Semester” shell and command-line environment lectures from MIT.

10.3 Tools and Documentation

  • Termux:API - Reference for client/add-on/signing requirements.
  • POSIX.1-2024 shell and utilities - Standard process and utility contracts.
  • Android adb and logcat documentation - Secondary evidence for controlled acceptance testing.

11. Self-Assessment Checklist

11.1 Understanding

  • I can explain which runtime facts Android owns and which Termux supplies.
  • I can explain why HOME and PREFIX must be validated rather than hard-coded.
  • I can distinguish client, add-on, signature, permission, provider, and hardware failures.
  • I can explain the classic same-signing-lineage rule and why the Play track differs.
  • I can defend every field included in a default support report.

11.2 Implementation

  • Human and JSON output derive from one typed report.
  • Every external probe has a deadline and output bound.
  • All public status and recovery codes are documented.
  • At least six failure fixtures pass without a physical phone.
  • Interactive and external launch results are meaningfully equivalent.
  • Canary secrets are absent from stdout, stderr, logs, and errors.

11.3 Growth

  • I recorded one incorrect desktop-Linux assumption I previously held.
  • I can explain one trade-off in my exit-status taxonomy.
  • I can present the architecture in a technical interview without notes.

12. Submission / Completion Criteria

Minimum Viable Completion

  • Runtime report covers track, Android/API, ABI, HOME, PREFIX, storage headroom, and required commands.
  • Human and JSON contracts agree.
  • Missing command, timeout, and malformed-response fixtures pass.
  • Default output contains no secret or persistent device identifier.

Full Completion

  • All minimum criteria plus layered classic add-on checks, Play-aware capability states, external-surface comparison, documented exit statuses, redaction tests, and six or more injected failure cases.

Excellence (Going Above and Beyond)

  • Report diffing, explicit uncertainty, consent-based anonymized compatibility evidence, and a third-party review of the schema and privacy model.

This guide was expanded from TERMUX_ANDROID_APPS_TOOLS_MASTERY.md. See the expanded project index for the complete learning path.