Dirextalk Deployer

Dirextalk Deployer

This skill is the compact agent-facing entrypoint. Treat this repository root as the execution engine and read the referenced docs only when that phase needs detail.

Entrypoints:

scripts/orchestrate.sh
scripts/destroy.sh
scripts/update.sh
scripts/reset-app-data.sh

Freshness Gate

On Windows, this check comes first, including before skill installation or refresh. Run it from Git Bash:

case "$(uname -s)" in
  MINGW*) git_root=$(git --exec-path 2>/dev/null | sed 's#/mingw64/libexec/git-core$##'); command -v git >/dev/null && command -v cygpath >/dev/null && git --version | grep -q '\.windows\.' && [ -n "$git_root" ] && [ "$(cygpath -m "${EXEPATH:-}" | tr '[:upper:]' '[:lower:]')" = "$(printf '%s/bin' "$git_root" | tr '[:upper:]' '[:lower:]')" ] ;;
  Linux*|Darwin*) true ;;
  *) false ;;
esac

Continue only when that command succeeds. Native Linux, macOS, and WSL sessions use their own Bash environment directly. On native Windows, it verifies that the current shell's EXEPATH is under the same Git for Windows installation as git, and rejects PowerShell, MSYS2, and Cygwin. Otherwise tell the Windows user to install Git for Windows from https://git-scm.com/download/win, reopen Git Bash, and stop. The skill CLI repeats and strengthens the Windows gate before install, update, or refresh can write a target.

Before deployment, repair, verification, teardown, runtime wiring, or skill installation, make one freshness attempt:

npm install -g dirextalk-deployer@latest
dirextalk-deployer skill refresh --agent <runtime>

Use project scope only when the user explicitly asks for repository-local installation:

dirextalk-deployer skill refresh --agent <runtime> --scope project --project <project-root>

If npm is unavailable, report that freshness could not be checked and continue with the local copy. If the user asks to install from YingSuiAI/dirextalk-deployer, do not use a generic GitHub skill installer; read the README and follow the npm install rule. Use a Git clone only for deployer development or local patching.

Platform Law

Classify every path by consumer before writing it to state.json, credentials.json, dirextalk-connect/config.toml, docs, or printed commands:

• Remote server paths are Linux paths consumed on EC2, such as /var/dirextalk-message-server.
• Deployer execution paths may be POSIX paths inside Bash phases.
• Local bridge paths are consumed by dirextalk-connect and local agent processes. On Windows they must be Windows-compatible paths.
• Documentation paths must be portable examples using $HOME, %USERPROFILE%, $env:USERPROFILE, <service_id>, or <domain>.

Windows, Linux, macOS, and WSL users run the same Bash entrypoints. A process running inside WSL is a Linux deployment host and uses its distribution's Node.js, AWS CLI, paths, and Bash directly. On native Windows, Git for Windows is required: use the exact preflight above before any deployment action. If it fails, tell the user to install Git for Windows from https://git-scm.com/download/win, open Git Bash, and rerun; do not substitute PowerShell or launch WSL as a command runner for a Windows-owned deployment. Git Bash automatically writes native C:/... paths for Windows-native Node.js, dirextalk-connect, and agent processes. Run every lifecycle action from that same Git Bash session:

DOMAIN=<domain> bash scripts/orchestrate.sh

The deployer explicitly normalizes file paths passed to native Node.js, AWS CLI, curl, and local agent tools. It does not depend on implicit MSYS argument conversion, so a parent runtime that sets MSYS_NO_PATHCONV=1 cannot turn a Git Bash /c/... or /tmp/... path into an unrelated C:\c\... or C:\tmp\... lookup.

Keep each local service in one environment: either native WSL/Linux paths or native Windows Git Bash paths. Do not switch the same service directory between PowerShell, WSL, and Git Bash.

Prerequisites And Confirmation

Do not deploy until the user has an active AWS account, a real long-lived domain, AWS credentials, DNS authority, and billing acknowledgement.

For first-time users, guide them step by step. Do not front-load the whole cloud setup checklist. Ask only the next blocking question, wait for the user's answer or completion, then continue to the next step.

Default tone for new users:

• Use product language such as account, domain, access key file, DNS provider, server, fixed IP, and monthly AWS cost.
• Avoid technical labels such as EC2, EIP, IAM policy, security group, EBS, Matrix server_name, Route53 hosted zone, federation identity, or TURN unless the user asks what they mean or the term appears in an AWS screen they must operate.
• When a technical term is unavoidable, explain it in one short sentence before asking the user to act.
• Never give a long architecture explanation during onboarding unless the user explicitly asks why the step is needed.

Step-by-step onboarding flow:

1. AWS account.

   • Shortcut: if the user already provided valid AWS credentials, such as a configured profile or a CSV that passed aws sts get-caller-identity, skip browser sign-in and email questions. The agent already has AWS access.
   • Ask: "Do you already have an AWS account you can log into?"
   • If yes, continue to the access key step.
   • If no, ask the user to open https://signin.aws.amazon.com/signup?request_type=register, register in their browser, complete payment/phone verification and Basic support selection if AWS asks, then stop until they say the account is ready.
   • Never ask for, collect, paste, log, or store payment card details, root password, MFA code, email verification code, or phone verification code.

2. AWS access key or profile.

   • Ask: "Do you already have an AWS access key CSV file or AWS profile for deployment?"
   • If yes, ask only for the local CSV path or profile name, then verify it.
   • If no, offer two credential paths and ask the user to choose:
     1. Root access key (default fastest path): simpler to create for a first deployment because it uses the account owner identity directly. Explain that it is highly privileged, must be saved securely, must never be pasted into chat or committed, and should be rotated or deleted after deployment.
     2. Dedicated IAM deployment user: safer because it avoids root keys, but requires more AWS console steps. Explain in one sentence: "This temporary DirextalkDeployer user with AdministratorAccess lets the deployment tool create and later destroy this Dirextalk node; delete or disable it after deployment."
   • Root access keys are allowed when the operator explicitly chooses them. Do not block deployment only because STS returns a root ARN; report root=true, repeat the security warning once, and continue if the user accepts that risk.
   • Prefer the repository helper for CSV import and redacted verification:

     bash scripts/aws-credentials.sh import-csv /path/to/accessKeys.csv dirextalk-deployer <region>
     export AWS_PROFILE=dirextalk-deployer
     bash scripts/aws-credentials.sh verify dirextalk-deployer

   • The agent may read the local CSV path, but must never print the Access Key ID together with the Secret Access Key, and must never write secrets into the repository, skill files, logs, or chat output.

3. Domain.

   • Ask: "Do you already own a long-lived domain or subdomain you want to use for this Dirextalk node?"
   • If yes, ask for the domain.
   • If no, first check whether the AWS account already has Route53 registered domains when AWS CLI access is available:

     aws route53domains list-domains --profile <profile>

     If domains exist, present only the domain names and ask whether to use one. If none exist, ask the user to buy or prepare a domain, then stop until they have it.
   • Do not ask where DNS is managed. After AWS credentials are available, the deployer checks for the longest matching public Route53 hosted zone in the current AWS account. If one exists it manages the A record automatically; otherwise it continues with external DNS and asks for the A record only after the fixed public IP exists.
   • Explain only this much by default: "Use a real long-term domain because changing it later means creating a new chat server identity."
   • Do not use localhost, raw IP addresses, wildcard domains, disposable domains, temporary sslip.io, or other throwaway names for production.

4. DNS control.

   • Let S2 query public Route53 hosted zones before asking any DNS-management question. A matching zone selects DOMAIN_MODE=route53; no matching zone selects DOMAIN_MODE=user without blocking infrastructure creation.
   • If Route53 listing fails, stop with an AWS credential/IAM error. Never misclassify an API failure as externally managed DNS.
   • For external DNS, wait until the script emits the fixed IP, then ask the user to create exactly:

     <DOMAIN>  A  <PUBLIC_IP>

   • If the user prefers Route53 while the domain is registered elsewhere, the hosted zone and NS delegation must be prepared explicitly first. The user or a provider-specific DNS connector must delegate those NS records at the current registrar before authoritative DNS can resolve.

5. Billing confirmation.

   • Give a short billing warning before the first mutating AWS command: "This will create paid AWS resources for the server. They keep billing until destroyed."
   • Provide an upfront monthly estimate for the selected region and cloud provider before asking for final approval. Use the pricing helper output; do not invent a fixed quote from memory.
   • Tell the operator that new AWS customer accounts generally receive 100-200 USD in free credits, and that users who have not used Lightsail generally receive three months of free Lightsail usage. Coverage is account-specific; recommend an AWS Budget and AWS Billing Console review, and say AWS official real-time policy prevails.
   • Check EC2-VPC Elastic IP quota before mutating AWS resources. For explicit EC2, also check default VPC, EC2 vCPU quota, and AMI availability.

Before final deployment confirmation:

aws lightsail get-regions --include-availability-zones --output json
bash scripts/pricing-estimate.sh --region <aws-region> --cloud-provider lightsail --domain-mode route53
bash scripts/pricing-estimate.sh --state ~/.dirextalk/nodes/<service_id>/state.json --write-state

Record and report cost_estimate and billing reminders. Tell the operator that new AWS customer accounts generally receive 100-200 USD in free credits, and that users who have not used Lightsail generally receive three months of free Lightsail usage. Coverage is account-specific; recommend an AWS Budget, AWS Billing Console review, and say AWS official real-time policy prevails. Check EC2-VPC Elastic IP quota before mutating AWS resources.

Required first-time deployment confirmation. Fill in the concrete domain, profile, region, and cloud provider. Include the AWS credit/Lightsail trial sentence immediately before asking for approval. Accept a natural-language confirmation in their own words; do not require them to copy a fixed sentence or a command token. Accept the confirmation only when it clearly covers all of the following:

• the intended Dirextalk deployment and final domain;
• the AWS profile or account authority and selected region/provider; and
• acknowledgement that billable resources can remain billed until destroyed.

Short replies such as "confirm", "deploy", or "go ahead" are sufficient only when the immediately preceding deployment summary already states those facts and the user has not changed the plan. Otherwise ask one concise follow-up that identifies the missing fact. Record the semantic user decision in the operation report, then set any required machine-only environment flags yourself.

Please confirm before I deploy. New AWS customer accounts generally receive 100-200 USD in free credits, and users who have not used Lightsail generally receive three months of free Lightsail usage. Credits and trials are account-specific, actual coverage must be verified in AWS Billing Console, and AWS official real-time policy prevails.

For example: "I confirm deployment of <domain> in <region>; I authorize this AWS profile and understand the ongoing AWS charges."

If any prerequisite is missing, stop deployment and guide the user through that specific step before running scripts/orchestrate.sh.

Required deployment env:

DOMAIN=<final-domain>
CONFIRM_DOMAIN_BINDING=1
DIREXTALK_CLOUD_PROVIDER=lightsail

Normal deployment consumes the deployer-owned production split release. Release preparation discovers the current application releases through latest, then records and deploys their stable vX.Y.Z image tags, source revisions, and real --version output. PostgreSQL/pgvector, Caddy, and coturn remain fixed dependencies, and the canonical runtime bundle is packaged with the deployer. The target host never clones a source repository and no mutable image override is part of the production path. The independent YingSuiAI/dirextalk-updater host binary is downloaded only on a verified Ubuntu 24.04+ x86_64 server with systemd >= 254 from the deployer-pinned Release URL and must match the deployer-pinned SHA-256. The local deployer host does not need Go and does not SCP updater artifacts. The updater pin and checksum contract remains independent from the default split release selection.

Fresh deployment installs the updater control plane with its resident watchdog disabled. Authorized update/recovery jobs remain available and retain their own recovery behavior. The updater does not install or run a daily GitHub release-discovery timer. After the direct-version migration, an authorized client/server release action creates the target-version job instead.

Leave DOMAIN_MODE unset for normal deployments. S2 automatically chooses route53 only when the current AWS account contains a matching public hosted zone; otherwise it chooses user and gives manual A-record guidance after IP allocation. Explicit DOMAIN_MODE=user|route53 remains an advanced automation override. If an existing Route53 A record points elsewhere, require an explicit semantic user confirmation that identifies the domain and the replacement target. Then set DIREXTALK_CONFIRM_DNS_OVERWRITE=1 internally. If Route53 delegation is needed, wait for authoritative DNS before continuing.

After the stable public IP exists, S3 revalidates the exact cloud instance, IP, AWS account, and SSH host, then runs authoritative and independent public- recursive DNS proof over SSH on that deployed host. Local dig output and DNS_READY=1 are diagnostic only and cannot bypass this gate; Caddy/ACME host integration starts only after the remote proof succeeds.

Default cloud provider is Lightsail. If no AWS region is configured in state, AWS_DEFAULT_REGION/AWS_REGION, or the AWS profile, the deployer recommends a default region from the local timezone and uses it in non-interactive runs; DIREXTALK_DEFAULT_REGION is the explicit deployer override. S1 queries Lightsail bundle availability and Lightsail availability zones before provisioning, but it does not query AWS Free Tier or credit usage. For manual Lightsail zone checks, use aws lightsail get-regions --include-availability-zones --output json; plain aws lightsail get-regions can omit availability-zone details. The default Lightsail zone is <region>a; if it is unavailable, S1/S3 select another available Lightsail zone in the same region. If Lightsail has no usable bundle or availability zone in the selected region, S1 records an EC2 cost estimate but does not automatically switch to EC2; ask the operator to choose another Lightsail-capable region/zone or explicitly rerun with DIREXTALK_CLOUD_PROVIDER=ec2 after reviewing the estimate. EC2 remains supported explicitly with DIREXTALK_CLOUD_PROVIDER=ec2; then S1 checks default VPC, EC2 vCPU quota, EC2-VPC Elastic IP quota, AMI availability, and S3 uses a 50 GiB gp3 root EBS volume.